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 DIRECTORY TILE OBJECTS ] }

You can have many locales in the Tiles dictionary object to support multiple languages.

For example:

  { "en-US" : [ ARRAY OF US DIRECTORY TILES ], "en-CA" : [ ARRAY OF CA DIRECTORY TILES ] }

Each Directory 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.

Directory 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.

Tiles/Technical Documentation

Contents