93 lines
3 KiB
ReStructuredText
93 lines
3 KiB
ReStructuredText
.. _Region:
|
|
|
|
======
|
|
Region
|
|
======
|
|
|
|
Firefox monitors the users region in order to show relevant local
|
|
search engines and content. The region is tracked in 2 properties:
|
|
|
|
* ``Region.current`` - The most recent location we detected for the user.
|
|
* ``Region.home`` - Where we consider the users home location.
|
|
|
|
These are tracked separately as to avoid updating the users
|
|
experience repeatedly as they travel for example. In general
|
|
callers should use ``Region.home``.
|
|
|
|
Region Updating
|
|
---------------
|
|
|
|
Firefox `uses a location service`_ that is provided by Mozilla. Firefox will
|
|
attempt to check for region on first run of a new profile and
|
|
`every 7 days thereafter`_. If an update check fails, then the update will be
|
|
retried `after an hour`_ for a `maximum of three times`_.
|
|
|
|
If the user is detected in a current region that is not their `home` region
|
|
for a continuous period (current 2 weeks) then their `home` region
|
|
will be updated.
|
|
|
|
Testing
|
|
=======
|
|
|
|
To set the users region for testing you can use:
|
|
|
|
.. code-block:: javascript
|
|
|
|
let {Region} = ChromeUtils.importESModule("resource://gre/modules/Region.sys.mjs");
|
|
Region._setHomeRegion("US", false)
|
|
|
|
Setting the second parameter (``notify``) to true will send an notification that
|
|
the region has changed and trigger a reload of search engines and other content.
|
|
|
|
Updating test_Region_geocoding.js data
|
|
--------------------------------------
|
|
|
|
Note: The geocoding feature is not turned on by default.
|
|
|
|
The test data used in this test is generated by running the MLS geocoding
|
|
service locally:
|
|
|
|
Follow the Ichnaea location development guide @ https://ichnaea.readthedocs.io/en/latest/local_dev.html.
|
|
|
|
Make a list of test locations in a CSV format, for example:
|
|
|
|
.. code-block:: shell
|
|
|
|
23.7818724,38.0531587
|
|
23.7728138,38.0572369
|
|
1.6780180,48.5973431
|
|
1.7034801,48.5979913
|
|
1.6978640,48.5919751
|
|
|
|
You can use the MLS raw data files to get a large sample @ https://location.services.mozilla.com/downloads
|
|
|
|
Save a script to run the geocoding in ``ichnaea/ichnaea``
|
|
|
|
.. code-block:: python
|
|
|
|
import geocode
|
|
geocoder = geocode.Geocoder()
|
|
|
|
f = open("mls.csv", "r")
|
|
r = open("mls-lookup-results.csv", "a")
|
|
|
|
for x in f:
|
|
[lat, long] = x.strip().split(",")
|
|
region = geocoder.region(lat, long)
|
|
r.write("%s\n" % region)
|
|
|
|
Run the script
|
|
|
|
.. code-block:: shell
|
|
|
|
$ make shell
|
|
$ cd ichnaea
|
|
$ python run.py
|
|
|
|
If you want to commit the new test data ~500 seems to be a reasonable
|
|
number of data points to test before running into issues with the test length.
|
|
|
|
.. _every 7 days thereafter: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/toolkit/modules/Region.sys.mjs#106
|
|
.. _uses a location service: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/modules/libpref/init/all.js#3107
|
|
.. _after an hour: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/toolkit/modules/Region.sys.mjs#32-40
|
|
.. _maximum of three times: https://searchfox.org/mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf/toolkit/modules/Region.sys.mjs#101
|