Tiles/Technical Documentation
Tiles Technical Documentation
For information about the progress and plans for Tiles see the Content services page.
For general information about Tiles and the New Tab page see the Tiles page.
This is technical information for advanced users or enterprise implementers on how Tiles are stored locally and fetched remotely and how you can change it.
Previously
Default Tiles were originally built into Desktop Firefox for en-US builds in the chrome://global/content/directoryLinks.json location. This file no longer exists in Firefox as Tiles are now downloaded from a web service. Additionally the preference ( browser.newtabpage.directorySource ) for Tiles has changed, the current details are listed below.
Preferences
There are two main preferences for Tiles that control fetching and metrics.
Source
This preference tells Firefox where to fetch Tiles from:
browser.newtabpage.directory.source = https://tiles.services.mozilla.com/v2/links/fetch
This preference can be set to anything that returns JSON, setting this to an empty JSON object will disable Tiles from showing and fetching new Tiles. With the change below a new user would only see empty Tiles and Firefox could no longer fetch new Tiles.
browser.newtabpage.directory.source = data:application/json,{}
Ping
This preference tells Firefox where Tiles metrics are reported:
browser.newtabpage.directory.ping = https://tiles.services.mozilla.com/v2/links/
Changing or disabling this pref may prevent Firefox from being able to report metrics on Tiles. Do not set this to alternate URLs, setting this to nothing will disable the ping.
Customizing Tiles
If you wanted to have a custom set of Default Tiles, for example in an Enterprise deployment, you could set the source preference to a custom set of local Tiles.
Here's an example of a custom default tiles source preference:
data:application/json,{
"en-US": [
{
"url" : "http://www.mozilla.org/",
"bgColor" : "%234d4e54",
"type": "custom",
"imageURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAABWCAQAAADMSHQwAAAFWklEQVR4AezBgQAAAACAoP2pF6kCAAAAAAAAAABgdu0sNqoyDOP4C1WWgCylKgqKoNRCqaxCiyx2bBGNAVrCJkRkUYFAMEGNVUjYRIIIuAYlBqKAUSBcWEUIBlDCBRU6pKINCAUU0CibbSyL9e%2FNmTdvpudMF2ZGj5nfc%2FcwyZCH6Xd6DlMXTGUbe1jEjYhJMgEK2M5WGiDYZDCJ1QTJRWId4f%2BTDwkpoanT5bKXcgDgEqJpyFrKCJmWGLr2ycNa4rQzQf1OY0RzFdTziaFrn41Yh%2FQTjSqnBaLZA2puYujaZy3Wt06bBepPkhFNIaj5iaFrn4FY0522F3boNohmE6gFiaHrkvmEbNQuw3PoDYlPdP0zmOWsYoRpunkOvT4xdDTj%2F6FpS3vESTo5ZNMBwaYBGeQQIBWJmNsZRB7DybJD1DvN6EE%2BraM0dGdyGct4HiMj3kM3pzdz%2BIzLnEIQ5lJKyC6ynVfdxFJOEPKd52%2Bqk9jNNUIq2MYYBJtxlNSQxc4%2F64t8ykEuAJB63UNns5ojWMdZRqv4DV0IahL7CTcN4UHOEO5rkhBsulOEm13Yn40CalKIICRhdbiOoZOYQRHufqFvvIZeTkgV7t7F3TLEpD%2FeLtIRcTKLmqxz5vk5KkM%2FQxmRXCU5PkPnUF%2BXzGf6VqqI5FeaOK98mer%2BxiqM6tDvUJMV8Rm6J%2BH28T5bwKXfQDHWPYiTHVgvkEZXXsLarJejMdiMJkAp1uyoDi2UgSpiDSvYjPV9fIZOw%2FqS3k6%2FAmunnmU%2Fgsp0uj5YeYiT8Vg9ENf0ohLUbiTKQ%2Fd1Xr2ENO2mgDpHo3gM3RnUAdMPAPWx6T8CNdDlAVAQMTkC9ux1STusq7SK%2BtDCVnbQLqyrJKSClvEYOhXUF6bPBDXd9B9UGzqJS56XyJWgziIuOYyVh8RgaLecJKQ8%2FkPvMn0WqHkeT9UGuJzyTyMm07A6IWFZhbUFifHQN9OF%2B%2BlPFmcJuUCzf3Po%2Fh5Dr6s29ONYwxCTfKyHEGyGYl0gKYZDj2U9pVRS3W808cfQz2IFIkyZj5i0oBJrEBKjoUdxFG9nuMEfQxdEmGsI1mjEZC%2FW60iMhp5HZKdo4I%2Bh50Q4Hh7Bsg88n8MqRWI0dIBwFfzECXOTdBzxx9ATI5zRo7AGYx%2FgWx1jNvRhrJX0ozUNSeEKIUf9MvQDWFMQk5lYd2h%2FGmsWEqOhO2EtNteHKkIO%2B2XoplwGtQgxeRvUSW0%2FwdqH1GvoSlI8hl6g7QisttrfBeqQX4YWPgf1FWJyDNR7TvckVhUpdRg6HdQ1bvG4Y12o7QSslq73oyX%2BGXoIVlePL8F0QxDuxKrkPqQOQ9%2BLlezx93rV4xqRqX17UBf9M7QQBHWeCbSmBeO4Uu3pXXNKsUrIYlhYRpLkOXQbz7vQt0Ad1LYb1iHnVO%2FFfqxh%2Fhk6FbAq%2BAPrvPPtueGA9RfVnaah59DCMaydPOz0U7FKWOt62T3PJnYQ7hyZfhlayMfbZdJqfpWagUQYugALtjl9S8I47zmO2gjGfuh0FD%2BYPtvjrq0QRQ5iEqAMN0G6mCcONWvlDG3dbb43egBcT%2BqJWPCafd4Y8b%2Foyuka%2B6E7UOwkyBrTdze9PQsXEtQ%2F6YnY0IjZFNmDgW94CjEZTHHEBHlTB91u%2BtsQM%2FUbVJj36Gt%2BqoIo1ms%2Fi9NYUEw%2FhNkAQIY%2Fv0DTiVzGMJps2iExSgqPMpknCJBCEmLSh%2FFMZgTpNDJtY%2FJZyga2spFXGKr9SIoYhfwXh%2F6nHToQAQAAAADkb73IbXCjR49u9OhGjx7d6NGNHj260aMbPXp0o0c3evToRo8OZGoOg%2BFHUXQAAAAASUVORK5CYII%3D",
"title": "Mozilla%20Foundation"
}
]
}
JSON Format
The Tile JSON format is a simple object, the top level needs to be a locale that Firefox understands. This object allows you to offer multiple locales in a single JSON file.
At a high level the data object looks like this:
{ "LOCALE" : [ ARRAY OF DEFAULT TILE OBJECTS ] }
You can have many locales in the Tiles dictionary object to support multiple languages.
For example:
{ "en-US" : [ ARRAY OF US DEFAULT TILES ], "en-CA" : [ ARRAY OF CA DEFAULT TILES ] }
Each Default Tile object requires a few attributes, most of which are self explanatory.
{
"url" : "http://www.mozilla.org/",
"bgColor" : "%234d4e54",
"type": "custom",
"imageURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAABWCAQAAADMSHQwAAAFWklEQVR4AezBgQAAAACAoP2pF6kCAAAAAAAAAABgdu0sNqoyDOP4C1WWgCylKgqKoNRCqaxCiyx2bBGNAVrCJkRkUYFAMEGNVUjYRIIIuAYlBqKAUSBcWEUIBlDCBRU6pKINCAUU0CibbSyL9e%2FNmTdvpudMF2ZGj5nfc%2FcwyZCH6Xd6DlMXTGUbe1jEjYhJMgEK2M5WGiDYZDCJ1QTJRWId4f%2BTDwkpoanT5bKXcgDgEqJpyFrKCJmWGLr2ycNa4rQzQf1OY0RzFdTziaFrn41Yh%2FQTjSqnBaLZA2puYujaZy3Wt06bBepPkhFNIaj5iaFrn4FY0522F3boNohmE6gFiaHrkvmEbNQuw3PoDYlPdP0zmOWsYoRpunkOvT4xdDTj%2F6FpS3vESTo5ZNMBwaYBGeQQIBWJmNsZRB7DybJD1DvN6EE%2BraM0dGdyGct4HiMj3kM3pzdz%2BIzLnEIQ5lJKyC6ynVfdxFJOEPKd52%2Bqk9jNNUIq2MYYBJtxlNSQxc4%2F64t8ykEuAJB63UNns5ojWMdZRqv4DV0IahL7CTcN4UHOEO5rkhBsulOEm13Yn40CalKIICRhdbiOoZOYQRHufqFvvIZeTkgV7t7F3TLEpD%2FeLtIRcTKLmqxz5vk5KkM%2FQxmRXCU5PkPnUF%2BXzGf6VqqI5FeaOK98mer%2BxiqM6tDvUJMV8Rm6J%2BH28T5bwKXfQDHWPYiTHVgvkEZXXsLarJejMdiMJkAp1uyoDi2UgSpiDSvYjPV9fIZOw%2FqS3k6%2FAmunnmU%2Fgsp0uj5YeYiT8Vg9ENf0ohLUbiTKQ%2Fd1Xr2ENO2mgDpHo3gM3RnUAdMPAPWx6T8CNdDlAVAQMTkC9ux1STusq7SK%2BtDCVnbQLqyrJKSClvEYOhXUF6bPBDXd9B9UGzqJS56XyJWgziIuOYyVh8RgaLecJKQ8%2FkPvMn0WqHkeT9UGuJzyTyMm07A6IWFZhbUFifHQN9OF%2B%2BlPFmcJuUCzf3Po%2Fh5Dr6s29ONYwxCTfKyHEGyGYl0gKYZDj2U9pVRS3W808cfQz2IFIkyZj5i0oBJrEBKjoUdxFG9nuMEfQxdEmGsI1mjEZC%2FW60iMhp5HZKdo4I%2Bh50Q4Hh7Bsg88n8MqRWI0dIBwFfzECXOTdBzxx9ATI5zRo7AGYx%2FgWx1jNvRhrJX0ozUNSeEKIUf9MvQDWFMQk5lYd2h%2FGmsWEqOhO2EtNteHKkIO%2B2XoplwGtQgxeRvUSW0%2FwdqH1GvoSlI8hl6g7QisttrfBeqQX4YWPgf1FWJyDNR7TvckVhUpdRg6HdQ1bvG4Y12o7QSslq73oyX%2BGXoIVlePL8F0QxDuxKrkPqQOQ9%2BLlezx93rV4xqRqX17UBf9M7QQBHWeCbSmBeO4Uu3pXXNKsUrIYlhYRpLkOXQbz7vQt0Ad1LYb1iHnVO%2FFfqxh%2Fhk6FbAq%2BAPrvPPtueGA9RfVnaah59DCMaydPOz0U7FKWOt62T3PJnYQ7hyZfhlayMfbZdJqfpWagUQYugALtjl9S8I47zmO2gjGfuh0FD%2BYPtvjrq0QRQ5iEqAMN0G6mCcONWvlDG3dbb43egBcT%2BqJWPCafd4Y8b%2Foyuka%2B6E7UOwkyBrTdze9PQsXEtQ%2F6YnY0IjZFNmDgW94CjEZTHHEBHlTB91u%2BtsQM%2FUbVJj36Gt%2BqoIo1ms%2Fi9NYUEw%2FhNkAQIY%2Fv0DTiVzGMJps2iExSgqPMpknCJBCEmLSh%2FFMZgTpNDJtY%2FJZyga2spFXGKr9SIoYhfwXh%2F6nHToQAQAAAADkb73IbXCjR49u9OhGjx7d6NGNHj260aMbPXp0o0c3evToRo8OZGoOg%2BFHUXQAAAAASUVORK5CYII%3D",
"title": "Mozilla%20Foundation"
}
NOTE: You need to URL escape all the text, in the bgColor you'll see the # is replaced with %23 and the spaces are replaced with %20 in the title.
Default Tiles Object Attributes
- url is the URL you want the Tile to link to
- bgColor provides a background fill color in case the image doesn't fill the space
- type isn't needed for custom tiles so please use the 'custom' attribute
- imageURI provides the full URL to the image you want centered. Images need to be properly sized for the Tiles.
- title provides the display text that will appear below the Tile and for the link title attribute.
- enhancedImageURI provides the full URL to the roll over image you want centered. Images need to be properly sized for the Tiles. If included a "Roll Over" image will be the image seen until a user mouses over the Tile, on mouse over the imageURI is then shown.
Source Code
- Firefox code related to the new tab page that powers Tiles.
- Onyx is a link server and engagement metrics aggregator for Firefox Tiles handling the delivery and receiving the metrics of Tiles via 3 data endpoints.
- Infernyx contains the rules to extract the metrics data and handles the immediate data processing of raw received data into aggregate data.
- Splice is our ingestion, validation, and authoring tool that makes sure tiles are processed, then published to the correct locale and country for Firefox users. It also contains the schemas for the metrics data.