summaryrefslogtreecommitdiffstats
path: root/application/basilisk/docs/DirectoryLinksProvider.rst
diff options
context:
space:
mode:
authorwolfbeast <mcwerewolf@gmail.com>2018-06-04 13:17:38 +0200
committerwolfbeast <mcwerewolf@gmail.com>2018-06-04 13:17:38 +0200
commita1be17c1cea81ebb1e8b131a662c698d78f3f7f2 (patch)
treea92f7de513be600cc07bac458183e9af40e00c06 /application/basilisk/docs/DirectoryLinksProvider.rst
parentbf11fdd304898ac675e39b01b280d39550e419d0 (diff)
downloadUXP-a1be17c1cea81ebb1e8b131a662c698d78f3f7f2.tar
UXP-a1be17c1cea81ebb1e8b131a662c698d78f3f7f2.tar.gz
UXP-a1be17c1cea81ebb1e8b131a662c698d78f3f7f2.tar.lz
UXP-a1be17c1cea81ebb1e8b131a662c698d78f3f7f2.tar.xz
UXP-a1be17c1cea81ebb1e8b131a662c698d78f3f7f2.zip
Issue #303 Part 1: Move basilisk files from /browser to /application/basilisk
Diffstat (limited to 'application/basilisk/docs/DirectoryLinksProvider.rst')
-rw-r--r--application/basilisk/docs/DirectoryLinksProvider.rst278
1 files changed, 278 insertions, 0 deletions
diff --git a/application/basilisk/docs/DirectoryLinksProvider.rst b/application/basilisk/docs/DirectoryLinksProvider.rst
new file mode 100644
index 000000000..c6f55c3d4
--- /dev/null
+++ b/application/basilisk/docs/DirectoryLinksProvider.rst
@@ -0,0 +1,278 @@
+=============================================
+Directory Links Architecture and Data Formats
+=============================================
+
+Directory links are enhancements to the new tab experience that combine content
+Firefox already knows about from user browsing with external content. There are
+3 kinds of links:
+
+- directory links fill in additional tiles on the new tab page if there would
+ have been empty tiles because the user has a clean profile or cleared history
+- suggested links are shown if certain triggering criteria matches the user's
+ browsing behavior, i.e., if the user has a top site that matches one of
+ several possible sites. E.g., only show a sports suggestion if the user has a
+ sport site as a top site
+- enhanced links replace a matching user's visible history tile from the same
+ site but only the visual aspects: title, image, and rollover image
+
+To power the above features, DirectoryLinksProvider module downloads, at most
+once per 24 hours, the directory source links as JSON with enough data for
+Firefox to determine what should be shown or not. This module also handles
+reporting back data about the tiles via asynchronous pings that don't return
+data from the server.
+
+For the directory source and ping endpoints, the default preference values point
+to Mozilla key-pinned servers with encryption. No cookies are set by the servers
+and Firefox enforces this by making anonymous requests.
+
+- default directory source endpoint:
+ https://tiles.services.mozilla.com/v3/links/fetch/%LOCALE%/%CHANNEL%
+- default directory ping endpoint: https://tiles.services.mozilla.com/v3/links/
+
+
+Preferences
+===========
+
+There are two main preferences that control downloading links and reporting
+metrics.
+
+``browser.newtabpage.directory.source``
+---------------------------------------
+
+This endpoint tells Firefox where to download directory source file as a GET
+request. It should return JSON of the appropriate format containing the relevant
+links data. The value can be a data URI, e.g., an empty JSON object effectively
+turns off remote downloading: ``data:text/plain,{}``
+
+The preference value will have %LOCALE% and %CHANNEL% replaced by the
+appropriate values for the build of Firefox, e.g.,
+
+- directory source endpoint:
+ https://tiles.services.mozilla.com/v3/links/fetch/en-US/release
+
+``browser.newtabpage.directory.ping``
+-------------------------------------
+
+This endpoint tells Firefox where to report Tiles metrics as a POST request. The
+data is sent as a JSON blob. Setting it to empty effectively turns off reporting
+of Tiles data.
+
+A path segment will be appended to the endpoint of "view" or "click" depending
+on the type of ping, e.g.,
+
+- ``view`` ping endpoint: https://tiles.services.mozilla.com/v3/links/view
+- ``click`` ping endpoint: https://tiles.services.mozilla.com/v3/links/click
+
+
+Data Flow
+=========
+
+When Firefox starts, it checks for a cached directory source file. If one
+exists, it checks for its timestamp to determine if a new file should be
+downloaded.
+
+If a directory source file needs to be downloaded, a GET request is made then
+cacheed and unpacked the JSON into the different types of links. Various checks
+filter out invalid links, e.g., those with http-hosted images or those that
+don't fit the allowed suggestions.
+
+When a new tab page is built, DirectoryLinksProvider module provides additional
+link data that is combined with history link data to determine which links can
+be displayed or not.
+
+When a new tab page is shown, a ``view`` ping is sent with relevant tiles data.
+Similarly, when the user clicks on various parts of tiles (to load the page,
+pin, block, etc.), a ``click`` ping is sent with similar data. Both of these can
+trigger downloading of fresh directory source links if 24 hours have elapsed
+since last download.
+
+Users can turn off the ping with in-new-tab-page controls.
+
+As the new tab page is rendered, any images for tiles are downloaded if not
+already cached. The default servers hosting the images are Mozilla CDN that
+don't use cookies: https://tiles.cdn.mozilla.net/ and Firefox enforces that the
+images come from mozilla.net or data URIs when using the default directory
+source.
+
+
+Source JSON Format
+==================
+
+Firefox expects links data in a JSON object with top level keys each providing
+an array of tile objects. The keys correspond to the different types of links:
+``directory``, ``suggested``, and ``enhanced``.
+
+Example
+-------
+
+Below is an example directory source file::
+
+ {
+ "directory": [
+ {
+ "bgColor": "",
+ "directoryId": 498,
+ "enhancedImageURI": "https://tiles.cdn.mozilla.net/images/d11ba0b3095bb19d8092cd29be9cbb9e197671ea.28088.png",
+ "imageURI": "https://tiles.cdn.mozilla.net/images/1332a68badf11e3f7f69bf7364e79c0a7e2753bc.5316.png",
+ "title": "Mozilla Community",
+ "type": "affiliate",
+ "url": "http://contribute.mozilla.org/"
+ }
+ ],
+ "enhanced": [
+ {
+ "bgColor": "",
+ "directoryId": 776,
+ "enhancedImageURI": "https://tiles.cdn.mozilla.net/images/44a14fc405cebc299ead86514dff0e3735c8cf65.10814.png",
+ "imageURI": "https://tiles.cdn.mozilla.net/images/20e24aa2219ec7542cc8cf0fd79f0c81e16ebeac.11859.png",
+ "title": "TurboTax",
+ "type": "sponsored",
+ "url": "https://turbotax.intuit.com/"
+ }
+ ],
+ "suggested": [
+ {
+ "adgroup_name": "open-source browser",
+ "bgColor": "#cae1f4",
+ "check_inadjacency": true,
+ "directoryId": 702,
+ "explanation": "Suggested for %1$S enthusiasts who visit sites like %2$S",
+ "frecent_sites": [
+ "addons.mozilla.org",
+ "air.mozilla.org",
+ "blog.mozilla.org",
+ "bugzilla.mozilla.org",
+ "developer.mozilla.org",
+ "etherpad.mozilla.org",
+ "hacks.mozilla.org",
+ "hg.mozilla.org",
+ "mozilla.org",
+ "planet.mozilla.org",
+ "quality.mozilla.org",
+ "support.mozilla.org",
+ "treeherder.mozilla.org",
+ "wiki.mozilla.org"
+ ],
+ "frequency_caps": {"daily": 3, "total": 10},
+ "imageURI": "https://tiles.cdn.mozilla.net/images/9ee2b265678f2775de2e4bf680df600b502e6038.3875.png",
+ "time_limits": {"start": "2014-01-01T00:00:00.000Z", "end": "2014-02-01T00:00:00.000Z"},
+ "title": "Thanks for testing!",
+ "type": "affiliate",
+ "url": "https://www.mozilla.com/firefox/tiles"
+ }
+ ]
+ }
+
+Link Object
+-----------
+
+Each link object has various values that Firefox uses to display a tile:
+
+- ``url`` - string url for the page to be loaded when the tile is clicked. Only
+ https and http URLs are allowed.
+- ``title`` - string that appears below the tile.
+- ``type`` - string relationship of the link to Mozilla. Expected values:
+ affiliate, organic, sponsored.
+- ``imageURI`` - string url for the tile image to show. Only https and data URIs
+ are allowed.
+- ``enhancedImageURI`` - string url for the image to be shown before the user
+ hovers. Only https and data URIs are allowed.
+- ``bgColor`` - string css color for additional fill background color.
+- ``directoryId`` - id of the tile to be used during ping reporting
+
+Suggested Link Object Extras
+----------------------------
+
+A suggested link has additional values:
+
+- ``adgroup_name`` - string to override the hardcoded display name of the
+ triggering set of sites in Firefox.
+- ``check_inadjacency`` - boolean if true prevents the suggested link from being
+ shown if the new tab page is showing a site from an inadjacency list.
+- ``explanation`` - string to override the default explanation that appears
+ below a Suggested Tile. %1$S is replaced by the triggering adgroup name and
+ %2$S is replaced by the triggering site.
+- ``frecent_sites`` - array of strings of the sites that can trigger showing a
+ Suggested Tile if the user has the site in one of the top 100 most-frecent
+ pages.
+- ``frequency_caps`` - an object consisting of daily and total frequency caps
+ that limit the number of times a Suggested Tile can be shown in the new tab
+ per day and overall.
+- ``time_limits`` - an object consisting of start and end timestamps specifying
+ when a Suggested Tile may start and has to stop showing in the newtab.
+ The timestamp is expected in ISO_8601 format: '2014-01-10T20:00:00.000Z'
+
+The inadjacency list is packaged with Firefox as base64-encoded 1-way-hashed
+sites that tend to have adult, gambling, alcohol, drug, and similar content.
+Its location: chrome://browser/content/newtab/newTab.inadjacent.json
+
+The preapproved arrays follow a policy for determining what topic grouping is
+allowed as well as the composition of a grouping. The topics are broad
+uncontroversial categories, e.g., Mobile Phone, News, Technology, Video Game,
+Web Development. There are at least 5 sites within a grouping, and as many
+popular sites relevant to the topic are included to avoid having one site be
+clearly dominant. These requirements provide some deniability of which site
+actually triggered a suggestion during ping reporting, so it's more difficult to
+determine if a user has gone to a specific site.
+
+
+Ping JSON Format
+================
+
+Firefox reports back an action and the state of tiles on the new tab page based
+on the user opening a new tab or clicking a tile. The top level keys of the
+ping:
+
+- ``locale`` - string locale of the Firefox build
+- ``tiles`` - array of tiles ping objects
+
+An additional key at the top level indicates which action triggered the ping.
+The value associated to the action key is the 0-based index into the tiles array
+of which tile triggered the action. Valid actions: block, click, pin, sponsored,
+sponsored_link, unpin, view. E.g., if the second tile is being clicked, the ping
+will have ``"click": 1``
+
+Example
+-------
+
+Below is an example ``click`` ping with 3 tiles: a pinned suggested tile
+followed by a history tile and a directory tile. The first tile is being
+blocked::
+
+ {
+ "locale": "en-US",
+ "tiles": [
+ {
+ "id": 702,
+ "pin": 1,
+ "past_impressions": {"total": 5, "daily": 1},
+ },
+ {},
+ {
+ "id": 498,
+ }
+ ],
+ "block": 0
+ }
+
+Tiles Ping Object
+-----------------
+
+Each tile of the new tab page is reported back as part of the ping with some or
+none of the following optional values:
+
+- ``id`` - id that was provided as part of the downloaded link object (for all
+ types of links: directory, suggested, enhanced); not present if the tile was
+ created from user behavior, e.g., visiting pages
+- ``past_impressions`` - number of impressions (new tab "views") a suggested
+ tile was shown before it was clicked, pinned or blocked. Where the "total"
+ counter is the overall number of impressions accumulated prior to a click action,
+ and "daily" counter is the number impressions occurred on same calendar day of
+ a click. This infomration is submitted once per a suggested tile upon click,
+ pin or block
+- ``pinned`` - 1 if the tile is pinned; not present otherwise
+- ``pos`` - integer position if the tile is not in the natural order, e.g., a
+ pinned tile after an empty slot; not present otherwise
+- ``score`` - integer truncated score based on the tile's frecency; not present
+ if 0
+- ``url`` - empty string if it's an enhanced tile; not present otherwise