MozillaWiki - User contributions [en]

Mobile/Fennec/Architecture

2017-07-23T07:29:34Z

Nevin: Add some notes about Fennec architecture update.

Note: Fennec's architecture has changed and a lot of componets are moved to Java Native UI. But it's sitll nice to have a look to understand previous Fennec design :)

==Background==

Fennec is a XUL-based web browser designed for mobile-class devices, especially those with touchscreen support. Fennec shares much of its platform support with Firefox. The two browsers use the exact same HTML rendering engine, as well as Add-on support, Download management, Places bookmarking & history, and JavaScript engine (including JIT support).

Although the underlying platform is the same, the front-end UI is very different. Fennec is designed for smaller screens, lower CPU & memory specs, non-qwerty keyboards and touchscreens. Because of the large UI differences, add-ons that overlay the Firefox UI would need to be ported to work in Fennec. The focus on acceptable performance while running on mobile-class devices coupled with some of the finger-based UI features, has resulted in some unique XUL structure.

==Application Structure==

===Browsing===

Fennec and Firefox are very different when it comes to the way HTML is presented. Firefox uses a <code><tabbrowser></code> XUL element to create a tabbed browsing environment. The <code><tabbrowser></code> is a composite control, made up of <code><browser></code> elements contained inside a modified <code><tabbox></code> element. Primary interaction is done through the <code><browser></code>.

[[Image: Mobile-typical-structure.png]]

Fennec takes a different approach. While <code><browser></code> elements are still used to render the HTML, they are hidden offscreen. The rendered HTML is drawn into a <code><canvas></code> element, which acts as the primary display surface. This is primarily done for the ease in which panning and zooming can be done at acceptable levels of performance. A tabbed browsing environment is created by using an additional strip of thumbnails representing the currently opened <code><browser></code> elements.

[[Image: Mobile-fennec-structure.png]]

The contents of the <code><browser></code> is copied to the <code><canvas></code>. The thumbnail used to represent the "tab" is updated either from the display <code><canvas></code>, for speed, or from the <code><browser></code> if the display <code><canvas></code> is stale.

Fennec uses the new [https://developer.mozilla.org/en/Gecko-Specific_DOM_Events#MozAfterPaint MozAfterPaint] event to optimize all DHTML updates to the the primary <code><canvas></code> display surface. Whenever the contents of the web page changes, for whatever reason, we only update the areas that actually changed. We don’t repaint the entire surface unless it's absolutely required.

===Chrome Elements===

All of the primary UI elements are children of a <code><stack></code>. This allows the UI elements to be absolutely positioned relative to each other, but mostly, relative to the primary <code><canvas></code> display surface.

[[Image: Mobile-fennec-stack.png]]

Fennec uses a JavaScript helper object, WidgetStack.js, to coordinate panning the individual UI elements. WidgetStack also manages the size to the content viewport. For the most part, the left and right toolstrips are "glued" to the sides of the content display surface. Different web pages are different widths (and heights) and as the width changes, the right toolstrip moves with the growing content. This means wider web pages require more pans to get to the right toolstrip.

Fennec tries to not use any dialogs. There are still some, used by the platform, but we are working to removing them all. Instead of dialogs, Fennec uses other UI to interact with the user. Firefox does similar things with modeless notification boxes and error pages in content.

In those situations where a dialog or secondary window would be used, Fennec typically brings a pseudo-panel into view. Fennec does not use real <code><panel></code> elements, as those tend to cause performance issues. Instead, a <code><vbox></code> containing the desired UI is brought into view. The boxes are children of the <code><stack></code>, can be positioned as needed, and are hidden until needed - also to improve startup performance.

Some examples are Bookmark List, Bookmark Editor and the Tools Panel (Add-ons, Preferences and Downloads). These elements are very similar to the toolstrips, but they are not managed by the WidgetStack.

===Panning/Zooming===

Panning moves the entire UI, not just the content area. The toolstrips and the content move as a single entity. It should feel as though the entire browser is being moved by your finger.

The <code><canvas></code> display surface displays the visible part of the web content. However, a little more than the visible area is actually drawn into the <code><canvas></code>. This allows panning to immediately show parts just "off screen" as the area moves. Also note, the entire web content is never drawn into the <code><canvas></code>. That would seriously slow down performance.

While panning moves the entire UI, zooming only affects the content area. However, the content are does "grow" when zoomed, so the right toolstrip seems farther to the right then when the content is not zoomed.

==Performance Related Coding Guidelines==

===Panels===

Using <code><panel></code> elements to float chrome UI over the main window leads to performance problems. In fact, any XUL element that creates a native OS window under the covers will slow things down. In Firefox, the awesomebar autocomplete list uses a <code><panel></code>. The autocomplete list was re-worked such that it was a <code><vbox></code> in the main <code><stack></code> and the results were dramatic. The list displays much faster.

===Showing/Hiding Elements===

Stacking two or more elements and then toggling the visiblilty of all but one element is a simple way to create a UI that changes based on a state. While useful, this showing/hiding process can be slow. Try to avoid if possible, or find other ways to achieve the same goal.

The URLbar in Firefox is a good example. When displaying the current web page URL, it is a <code><description></code>. But when the user is typing a new URL, it is a <code><textbox></code>. The process of showing/hiding the elements was taking a noticeable amount of time, affecting the perceived page loading time. In Fennec, the URLbar is always a <code><textbox></code>. The <code>readOnly</code> property is toggled to create the "caption" mode.

A similar situation occurred with the favicon indicator. Fennec initially used a <code><stack></code> holding two <code><image></code> elements - one for the throbber and another for the website’s favicon. Again, we were showing and hiding the images depending on situation. This time it was the <stack> that was the slow down. So it was removed and page loading appeared to complete a little faster. The two image elements were kept because the load time for the swapping the favicon image with the throbber image eclipsed any benefits of removing the show/hide code.

===Canvas and Thumbnails===

As described above, Fennec copies the contents of a <code><browser></code> to the display <code><canvas></code>. Updating the contents of a browser to a canvas is not cheap on mobile devices. Each <code>drawWindow</code> call can take ~300-400ms. On the other hand, <code>drawImage</code> is much faster - ~100ms. Fennec uses <code>drawImage</code> whenever possible to update the tab thumbnails.

Fennec also uses the MozAfterPaint event to optimize all DHTML updates to the the main canvas display surface. This minimizes the amount of <code>drawWindow</code> calls. We don't repaint the entire canvas.

===Post-Pageload Work===

Any work that occurs while the page is loading is potentially bad for performance. This includes any time consuming work that happens in the page "load" event handler. Users like to start interacting with page content as soon as possible. Fennec even delays updating the web page favicon until the page finishes loading.

Fennec also had a time consuming process, converting plain text phone numbers to tel: links, that fired as soon as the page loaded. This process blocked the user from interacting with the page for a noticeable time period. The process was re-worked and became much faster. The blocking behavior was no longer noticeable and the user could interact with the page faster.

===File I/O===

Various places in the platform had file I/O code that was slowing Fennec down, usually on startup. Keep in mind, file I/O on mobile devices is usually measured in milliseconds. So try to avoid useless I/O whenever possible. Fennec startup improved from around 30 seconds (yes) for a first-time, cold start in Alpha 1 to around 7-10 seconds in Alpha 2.

Leanplum Contextual Hints

2017-06-30T23:16:38Z

Nevin: Only keep important fields, and add a link to source code document.

==Test Plan (iOS & Android) - July 2017 ==
; '''Goal:'''
With the initial implementation of the Leanplum SDK into our mobile browser products, we want to start A/B testing contextual hints to increase retention.
; '''Overarching Hypothesis:'''
We believe that by promoting contextual hints that helps users explore and change settings within the browser, we will drive DAUs and retention.

==iOS==

; '''iOS Hypothesis 1:'''

We believe that by promoting Focus to our privacy conscious users inside Firefox, we will increase installs and DAUs in Focus, and increase retention on both apps (We know that users who have Focus and Firefox installed retain better (Adjust)).

; '''iOS Hypothesis 2:'''

We believe that by promoting Sync to our users inside Firefox, we will increase DAUs and retention as Firefox Account data shows that users with 2 synced devices retain longer.

{| class="wikitable"
|-
! Hyp. # !! Message Name !! Trigger !! Targets
|-
| H1 || Clear Private Data - Focus Promotion || Clear private data || Test: en-USPost-test: en, en-gb, de, zh-tw
|-
| H1 || Opened New Tab - Focus Promotion - Promote Default Browser || Open new tab || Test: en-USPost-test: en, en-gb, de, zh-tw
|-
| H2 || Open Bookmark - Sync Promotion || Open bookmark || Test: en-USPost-test: en, en-gb, de, zh-tw
|-
| H3 || Save Bookmark - Sync Promotion || Save bookmark || Test: en-USPost-test: en, en-gb, de, zh-tw
|}

==Android==

; '''Android Hypothesis 1:'''
We believe that by prompting users to change their default browser to Firefox, we will increase DAUs and retention.

; '''Android Hypothesis 2:'''
We believe that by promoting add-ons to our users inside Firefox, we will increase DAUs and retention.

; '''Android Hypothesis 3: '''
We believe that by promoting Sync to our users inside Firefox, we will increase DAUs and retention as Firefox Account data shows that users with 2 synced devices retain longer.

{| class="wikitable"
|-
! Hyp. # !! Message Name !! Trigger !! Targets
|-
| H1 || Launch Promote - Default Browser || App Start || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG
|-
| H1 || Load Bookmark - Promote Default Browser || Load bookmark || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG
|-
| H2 || Firefox launches - add-ons promotion || App start || Test: en-US Post-test: en, en-gb, en-ca, de, zh-tw in US, CA, AU, UK, DE, TW, HK, SG
|-
| H3 || Save Password - Promote Sync || Save password || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG
|}
For more detail about the triggers and deep links in Android, please go to this page[http://gecko.readthedocs.io/en/latest/mobile/android/fennec/mma.html]

Leanplum Contextual Hints

2017-06-30T17:35:26Z

Nevin: Edit the title

==Test Plan (iOS & Android) - July 2017 ==
; '''Goal:'''
With the initial implementation of the Leanplum SDK into our mobile browser products, we want to start A/B testing contextual hints to increase retention.
; '''Overarching Hypothesis:'''
We believe that by promoting contextual hints that helps users explore and change settings within the browser, we will drive DAUs and retention.

==iOS==

; '''iOS Hypothesis 1:'''

We believe that by promoting Focus to our privacy conscious users inside Firefox, we will increase installs and DAUs in Focus, and increase retention on both apps (We know that users who have Focus and Firefox installed retain better (Adjust)).

; '''iOS Hypothesis 2:'''

We believe that by promoting Sync to our users inside Firefox, we will increase DAUs and retention as Firefox Account data shows that users with 2 synced devices retain longer.

{| class="wikitable"
|-
! Hyp. # !! Message Name !! Trigger !! Deep Link !! Message Type !! Event & Timing !! Targets !! Result
|-
| H1 || Clear Private Data - Focus Promotion || Clear private data || Focus Adjust link || Banner || Clear Private Data once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|-
| H1 || Opened New Tab - Focus Promotion - Promote Default Browser || Open new tab || Focus Adjust link || Banner || Open new tab once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|-
| H2 || Open Bookmark - Sync Promotion || Open bookmark || firefox://open-url?deep-link=settings/fxa || Banner || Open bookmark once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|-
| H3 || Save Bookmark - Sync Promotion || Save bookmark || firefox://sign_up || Dialog/Banner || Save bookmark once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|}

==Android==

; '''Android Hypothesis 1:'''
We believe that by prompting users to change their default browser to Firefox, we will increase DAUs and retention.

; '''Android Hypothesis 2:'''
We believe that by promoting add-ons to our users inside Firefox, we will increase DAUs and retention.

; '''Android Hypothesis 3: '''
We believe that by promoting Sync to our users inside Firefox, we will increase DAUs and retention as Firefox Account data shows that users with 2 synced devices retain longer.

{| class="wikitable"
|-
! Hyp. # !! Message Name !! Trigger !! Deep Link !! Message Type !! Event & Timing !! Targets !! Result
|-
| H1 || Launch Promote - Default Browser || App Start || firefox://default_browser || Dialog || User starts app second time (only once)VsUser starts app third time (only once)One event a week or 2 weeks - ask Evan || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG || N/A
|-
| H1 || Load Bookmark - Promote Default Browser || Load bookmark || firefox://default_browser || Dialog || Load Bookmark (1st time) oncevsLoad Bookmark (2 times) onceVsLoad Bookmark (5 times) once || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG || N/A
|-
| H2 || Firefox launches - add-ons promotion || App start || http://addons.mozilla.org || Dialog || User starts app 2nd time (only once)One event a week or 2 weeks || Test: en-US Post-test: en, en-gb, en-ca, de, zh-tw in US, CA, AU, UK, DE, TW, HK, SG || N/A
|-
| H3 || Save Password - Promote Sync || Save password || firefox://sign_up || Dialog/Banner || Save Password once, banner shows up the next time you launch app || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG || N/A
|}

Leanplum Contextual Hints

2017-06-30T17:34:30Z

Nevin: First version for the document

= Leanplum Contextual Hints Test Plan (iOS & Android) - July 2017 =
; '''Goal:'''
With the initial implementation of the Leanplum SDK into our mobile browser products, we want to start A/B testing contextual hints to increase retention.
; '''Overarching Hypothesis:'''
We believe that by promoting contextual hints that helps users explore and change settings within the browser, we will drive DAUs and retention.

==iOS==

; '''iOS Hypothesis 1:'''

We believe that by promoting Focus to our privacy conscious users inside Firefox, we will increase installs and DAUs in Focus, and increase retention on both apps (We know that users who have Focus and Firefox installed retain better (Adjust)).

; '''iOS Hypothesis 2:'''

We believe that by promoting Sync to our users inside Firefox, we will increase DAUs and retention as Firefox Account data shows that users with 2 synced devices retain longer.

{| class="wikitable"
|-
! Hyp. # !! Message Name !! Trigger !! Deep Link !! Message Type !! Event & Timing !! Targets !! Result
|-
| H1 || Clear Private Data - Focus Promotion || Clear private data || Focus Adjust link || Banner || Clear Private Data once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|-
| H1 || Opened New Tab - Focus Promotion - Promote Default Browser || Open new tab || Focus Adjust link || Banner || Open new tab once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|-
| H2 || Open Bookmark - Sync Promotion || Open bookmark || firefox://open-url?deep-link=settings/fxa || Banner || Open bookmark once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|-
| H3 || Save Bookmark - Sync Promotion || Save bookmark || firefox://sign_up || Dialog/Banner || Save bookmark once || Test: en-USPost-test: en, en-gb, de, zh-tw || N/A
|}

==Android==

; '''Android Hypothesis 1:'''
We believe that by prompting users to change their default browser to Firefox, we will increase DAUs and retention.

; '''Android Hypothesis 2:'''
We believe that by promoting add-ons to our users inside Firefox, we will increase DAUs and retention.

; '''Android Hypothesis 3: '''
We believe that by promoting Sync to our users inside Firefox, we will increase DAUs and retention as Firefox Account data shows that users with 2 synced devices retain longer.

{| class="wikitable"
|-
! Hyp. # !! Message Name !! Trigger !! Deep Link !! Message Type !! Event & Timing !! Targets !! Result
|-
| H1 || Launch Promote - Default Browser || App Start || firefox://default_browser || Dialog || User starts app second time (only once)VsUser starts app third time (only once)One event a week or 2 weeks - ask Evan || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG || N/A
|-
| H1 || Load Bookmark - Promote Default Browser || Load bookmark || firefox://default_browser || Dialog || Load Bookmark (1st time) oncevsLoad Bookmark (2 times) onceVsLoad Bookmark (5 times) once || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG || N/A
|-
| H2 || Firefox launches - add-ons promotion || App start || http://addons.mozilla.org || Dialog || User starts app 2nd time (only once)One event a week or 2 weeks || Test: en-US Post-test: en, en-gb, en-ca, de, zh-tw in US, CA, AU, UK, DE, TW, HK, SG || N/A
|-
| H3 || Save Password - Promote Sync || Save password || firefox://sign_up || Dialog/Banner || Save Password once, banner shows up the next time you launch app || Test: en-USPost-test: en, en-gb, en-ca, de, zh-tw inUS, CA, AU, UK, DE, TW, HK, SG || N/A
|}

Mobile

2017-06-30T16:53:04Z

Nevin: Update the document for Leanplum

On Mobile devices there are essentially two initiatives Firefox Mobile and FirefoxOS.

== Firefox Mobile (Fennec) ==

"Fennec" is the code name of Mozilla's project to develop Firefox for mobile devices. For more information about Firefox Mobile, see the [[Mobile/Fennec|Fennec project page]] or [[Mobile/Get_Involved|get involved page]].

=== Goals ===

Bringing Firefox to mobile phones is the next step towards fulfilling Mozilla’s [http://www.mozilla.org/about/mission.html mission] of providing access to one Web that everyone can access, regardless of device or location. The overall goals for Mobile Firefox are:

* Provide a platform for developers to create compelling content and applications using the latest Web technologies like HTML5, CSS and JavaScript.
* Deliver an exceptional mobile experience to users, complete with the performance, personalization and security they expect.
* Do all of this work in the shared Mozilla source repositories so all platforms, desktop and mobile, benefit each other.

For more background on our goals please see [[Mobile/Background|these blog posts]]. Still have questions? See our [http://www.mozilla.com/en-US/mobile/faq/ Mobile FAQ].

== Mobile Marketing Automation ==
Fennec uses an external tool to help engaging with users. The tool we are using is Leanplum. For details about the running campaign, please visit [[Leanplum Contextual Hints]] page.

== Firefox OS ==

* "[[B2G]]" (Boot To Gecko) is the code name of Mozilla's project to develop an OS for Mobile devices entirely based on open Web technologies.
* [[Gaia]] is the collection of web apps which make up the front end of [[FirefoxOS|Firefox OS]].

== Mobile Web Compatibility ==

Some Web sites are coding for very specific browsers. It creates [[Compatibility/Mobile|Mobile Web Compatibility]] issues for Firefox for Android and Firefox OS. You can [[Compatibility/Guide|help Mozilla]] solve these issues.

Mobile

2017-06-30T16:46:14Z

Nevin: Create a page for Leanplum

On Mobile devices there are essentially two initiatives Firefox Mobile and FirefoxOS.

== Firefox Mobile (Fennec) ==

"Fennec" is the code name of Mozilla's project to develop Firefox for mobile devices. For more information about Firefox Mobile, see the [[Mobile/Fennec|Fennec project page]] or [[Mobile/Get_Involved|get involved page]].

=== Goals ===

Bringing Firefox to mobile phones is the next step towards fulfilling Mozilla’s [http://www.mozilla.org/about/mission.html mission] of providing access to one Web that everyone can access, regardless of device or location. The overall goals for Mobile Firefox are:

* Provide a platform for developers to create compelling content and applications using the latest Web technologies like HTML5, CSS and JavaScript.
* Deliver an exceptional mobile experience to users, complete with the performance, personalization and security they expect.
* Do all of this work in the shared Mozilla source repositories so all platforms, desktop and mobile, benefit each other.

For more background on our goals please see [[Mobile/Background|these blog posts]]. Still have questions? See our [http://www.mozilla.com/en-US/mobile/faq/ Mobile FAQ].

== Mobile Marketing Automation ==
Fennec uses an external tool to help engaging with users. The tool we are using is Leanplum. For details about the running campaign, please visit [[Leanplum]] page.

== Firefox OS ==

* "[[B2G]]" (Boot To Gecko) is the code name of Mozilla's project to develop an OS for Mobile devices entirely based on open Web technologies.
* [[Gaia]] is the collection of web apps which make up the front end of [[FirefoxOS|Firefox OS]].

== Mobile Web Compatibility ==

Some Web sites are coding for very specific browsers. It creates [[Compatibility/Mobile|Mobile Web Compatibility]] issues for Firefox for Android and Firefox OS. You can [[Compatibility/Guide|help Mozilla]] solve these issues.

Mobile/Fennec/Android/Switchboard

2017-06-02T11:28:01Z

Nevin: Bug 1369685 - Add a new key "region" on Switchboard

Switchboard is a service we use to segment users for A/B testing or staged rollout of features.

An experiment can be enabled for a specified percentage of users and limited to release channels, app versions, languages, countries (locale), device names and device manufacturers. An experiment can contain additional metadata to "configure" the experiment. This can be used to change parameters of an experiment without needing to ship a new app version. Which experiments a user is enrolled in is reported to our telemetry systems via the core ping.

== History ==

We started with [https://github.com/KeepSafe/Switchboard KeepSafe's Switchboard library] and server component but since then the code and architecture has changed significantly. The original implementation used a special [https://github.com/mozilla-services/switchboard-server switchboard server] that did decides which experiments a client is part of and then just returns a simplified list for the client to consume. This required the client to send data (including a unique id) to the server. To avoid this and make the administration of experiments simpler we moved to using Kinto as storage and server of the experiment configuration. Now clients load the whole configuration and decide independently what experiments they are enrolled it.

== Summary ==

* The experiment configuration is stored in [http://kinto.readthedocs.io/en/stable/ Kinto] and served from a CDN: https://firefox.settings.services.mozilla.com/v1/buckets/fennec/collections/experiments/records
* The client regularly loads the configuration (or diffs, see Kinto API) and stores it locally.
* Based on a UUID for bucketing the client and using the experiment filters the client decide which experiments it is part of.
* The experiment configuration can be modified using the Kinto web admin (VPN + account whitelisting required)

== Adding a new experiment ==

=== Client ===

=== Server side ===

* Go to https://settings-writer.prod.mozaws.net/v1/admin (You need to be on the Mozilla network, either in an office or via VPN)
* Login with your LDAP credentials (Your account needs to be whitelisted)
* Follow the Web UI to create or modify an experiment. See below for an explanation of the fields.
* Currently saved changes go live immediately! The Kinto team is setting up a process for a mandatory review step.

=== Client side ===

* Add your experiment name to [https://dxr.mozilla.org/mozilla-central/source/mobile/android/base/java/org/mozilla/gecko/Experiments.java Experiments.java]
* Use [https://dxr.mozilla.org/mozilla-central/source/mobile/android/base/java/org/mozilla/gecko/switchboard/SwitchBoard.java SwitchBoard.isInExperiment()] to check whether the client is part of your experiment.
* Use SwitchBoard.getExperimentValuesFromJson() if you have configured additional metadata for your experiment.

=== Testing ===

* There's an add-on that you can use for overriding the local switchboard configuration: [https://addons.mozilla.org/en-US/android/addon/switchboard-experiments/ Addon Download] [https://github.com/pocmo/Addon-Switchboard-Experiments Source code]. This works great for switching experiments on/off - but doesn't let you configure additional metadata if required by the experiment.

== Experiment configuration ==

* '''Name''': A descriptive name for the experiment. This name is used in JSON that is being sent by the server and stored by the client. Examples are: ''bookmark-history-menu'', ''malware-download-protection'', ''promote-add-to-homescreen''
* '''Description''': A more detailed description what this experiment is about. In the best case this contains a bug number for context. Currently we send this data to the clients too (Don't make it too big).
* '''Regions''': It check the country we get in the search engine manager (e.g. US, TW). If there's no value stored we just think we are not in the experiment. In the admin interface, it should be a list (e.g {'US','TW'} ).
* '''Buckets''': Every user is in one of 100 buckets (0-99). For every experiment you can set up a min and max value (0 <= min <= max <= 100). The bounds are [min, max). An experiment set to buckets min=0, max=50 means that users in buckets 0-49 will have it enabled. There is no check for out of bounds values, so "disabled" experiments can have min/max buckets keys that are either out of bounds or have min == max. A disabled experiment is usually set to min=0, max=0.
* '''Filters''' - In addition to buckets additional filters can be used to limit the experiments to a subset of users.
** appId (regex): The Android app ID (e.g. org.mozilla.fennec, org.mozilla.firefox_beta, org.mozilla.firefox)
** version (regex): The Firefox app version number (e.g. 47.0a1', 46.0)
** lang (regex): Language, pulled from the default locale (e.g. eng)
** country (regex): Country, pulled from the default locale (e.g. USA)
** device (regex): Android device name
** manufacturer (regex): Android device manufacturer
* '''values''': Every experiment can include an optional JSON object with values that are used by the experiment. For example an experiment showing a bookmark dialog after a page has been visited multiple times, could use a value that defines how many visits are needed to display the dialog. With that the experiment can change without needing to update the app.

Mobile/Distribution Files

2017-04-06T08:44:56Z

Nevin: fix the typo and add comma

Like [https://wiki.mozilla.org/Distribution_INI_File desktop], mobile Firefox supplies a way for partners to repackage a set of customization files into a Firefox build without recompiling. We don't want to make custom binary builds that need to be QA'd extensively. The "distribution files" concept allows a small set of external files to be used to customize a standard Firefox build. Things that can be customized include:
* Default bookmarks
* Preferences
* Lightweight themes
* Search engines
* Add-ons
* Quickshare defaults
* Suggested sites

A sample distribution directory is available on [https://github.com/mozilla/fennec-distribution-sample github].

==Overview==
There are currently three ways distribution files can be ... distributed:
# '''<big>APK distributions</big>''': A folder of distribution files is repackaged into the Android APK. During the first run, those files are extracted from the APK and stored in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory.
# '''<big>System distributions</big>''': A folder of distribution files are shipped with the ROM image in <code>/system/org.mozilla.firefox/distribution/*</code> directory. Shipping in this way ensures the files are not easily overwritten or removed by an application update. Note, files found in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory will "win" in cases where both locations are used.
# '''<big>Over-the-air distributions</big>''': A distribution zip file is downloaded over-the-air as a result of a post-install referrer intent. See {{bug|1013024}}. This feature should ship with Firefox 33.

Distributions are processed asynchronously during first run. Frontend code can chain post-distribution tasks via <code>Distribution.addOnDistributionReadyCallback</code>.

Each type of data has its own nuances:
* Default bookmarks are read from the APK directly or from the "distribution" folder (if it already exists) any time a profile is created. These bookmarks are created prior to Firefox's default bookmarks.
* Preferences are set as "default" preferences on each run, since a "default" preference only lasts for the lifetime of the session. They are created as "default" preferences to allow "user" preferences to override them.
* Lightweight themes are actually just preferences. The data for the theme must live online somewhere. Typical places are the AMO theme or getpersonas.com sites.
* Search engine plugins and add-ons must follow a fixed folder layout.
* If distribution data is processed after the initial quickshare set is loaded, these options won't take effect until next run ({{bug|1021176}}).

==Bookmarks==
Default bookmarks are specified in '''/distribution/bookmarks.json'''. This file should contain an array of bookmark JSON objects with the following properties:
* '''title''': (required) string for the bookmark title
* '''url''': (required) string for the bookmark URL
* title.<locale>: (optional) title string for the given locale
* url.<locale>: (optional) URL string for the given locale
* icon: (optional) data URI for the bookmark favicon
* pinned: (optional) boolean for whether or not to pin this bookmark to the about:home top sites
** NOTE: If a bookmark is pinned, it is not visible in the Bookmarks list. Pinning only affects Tops Sites.

Here is an example bookmarks.json:
[
{
"title": "Queso",
"url": "http://queso.com/",
"title.en_US": "Cheese",
"url.en_US": "http://cheese.com",
"icon": "data:image/png;base64,..."
}
]

==Preferences==
Preferences are specified in '''/distribution/preferences.json'''. This file should contain a JSON object with the following properties:
* Global
** '''id''': (required) a short string unique to this distribution
** '''version''': (required) version of the distribution (not the version of Firefox)
** '''about''': (required) a short descriptive (ui-visible) string for this distribution
** about.<locale>: (optional) descriptive string for the given locale
* Preferences (optional)
** This sets default Gecko preferences for the profile (i.e. prefs that would appear in about:config)
* LocalizablePreferences (optional)
* LocalizablePreferences.<locale> (optional)
* ApplicationPreferences (optional)
** This sets as the app-scoped SharedPreferences for the entire application. Since GeckoPreferenceFragment only accept application-scoped sharedPreferences, this object will let partner also have the ability to override them.
* AndroidPreferences (optional)
** This sets Android SharedPreferences for the profile

Here is an example preferences.json:
{
"Global": {
"id": "testpartner",
"version": 1.0,
"about": "Afiliado de Prueba",
"about.en-US": "Test Partner"
},
"Preferences": {
"distribution.test.string": "a string pref",
"distribution.test.boolean": true,
"distribution.test.int": 5
},
"LocalizablePreferences": {
"distribution.test.localizeable": "http://test.org/%LOCALE%/%LOCALE%/",
"distribution.test.localizeable-override": "http://test.org/%LOCALE%/%LOCALE%/"
},
"LocalizablePreferences.en-US": {
"distribution.test.localizeable-override": "http://cheese.com"
},
"ApplicationPreferences": {
"newtab.load_homepage": "true"
},
"AndroidPreferences": {
"homepage": "http://www.mozilla.com"
}
}

==Lightweight Themes==
Lightweight themes are specified in the "Preferences" section of /distribution/preferences.json. Here is an example of the lightweight theme preferences needed for this to work:

"Preferences": {
"lightweightThemes.isThemeSelected": true,
"lightweightThemes.persisted.footerURL": false,
"lightweightThemes.persisted.headerURL": false,
"lightweightThemes.usedThemes": "[{\"id\":\"491717\",\"name\":\"colored trees\",\"headerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees.png?1358076678\",\"footerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees-base.png?1358076678\",\"textcolor\":\"#1d022b\",\"accentcolor\":\"#000000\",\"iconURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview_small.jpg?1358076678\",\"previewURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview.jpg?1358076678\",\"author\":\"birdyann\",\"description\":\"trees arbres colored colors couleurs\",\"updateURL\":\"https://www.getpersonas.com/en-US/update_check/491717\",\"version\":\"1358076678\",\"updateDate\":1359579038207,\"installDate\":1359579038207}]"
}

==Search Plugins==
Include search plugins in a directory structure like the following, and they will be
automatically loaded:

* distribution/
* searchplugins/
* common/
* <plugin.xml>
* <plugin.xml>
* ...
* locale/
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...

If a directory for the locale the browser is running in doesn't exist, Firefox will automatically try the 'default' locale, as defined by the <code>distribution.searchplugins.defaultLocale</code> preference.

To set a given search engine as the default, you need to use <code>LocalizablePreferences</code> to override the <code>browser.search.defaultenginename</code> preference. You should also override the <code>browser.search.order.1</code> preference to put the default engine in the right sort order. For example:

{
...
"LocalizablePreferences": {
"browser.search.defaultenginename": "<name-of-engine>",
"browser.search.order.1": "<name-of-engine>"
...
}
...
}

==Add-ons==
Include add-ons in an extensions directory as follows, and they will be
automatically loaded:

* distribution/
* extensions/
* someaddon@somedomain.com.xpi
* ...

Be sure to name the add-on XPI with the ID that's specified in the add-on's install.rdf.

'''Note:''' As of Firefox 41, we require all add-ons to be signed through AMO, so you should make sure this XPI is signed properly before shipping in a distribution.

==Quickshare defaults==
Add a file named <code>history.xml</code> under <code>distribution/quickshare</code>. Its contents should be something like:

<pre>
<historical-records>
<historical-record activity="com.android.mms/com.android.mms.ui.ConversationComposer"
time="0"
weight="1"/>
</historical-records>
</pre>

==Suggested sites==
Added by {{bug|1012462}} in Firefox 33.

Use a directory tree like the following. Locales are named via a locale code, such as <code>en-US</code>.

* distribution/
* suggestedsites/
* locales/
* <locale>/
* suggestedsites.json
* res/
* hdpi/
* <distro>.png
* xxhdpi/
* <distro>.png

The suggestedsites.json file should be a JSON array:

[
{
url: "<site-url>",
title: "<site-title>",
imageurl: "gecko.distribution://<image-dir>/<image-name>",
bgcolor: "<color-hex-code>", /* "#FF00FF" with leading '#' */
trackingid: <tiles-id> /* optional integer */
},
...
]

Where <code><image-dir></code> is the directory containing the density-specific image directories (<code>mdpi</code>, <code>hdpi</code>, etc) and <code><image-name></code> is the filename under the density-specific directories without the file extension. For example, <code>gecko.distribution://suggestedsites/res/distroimage</code> image URL will be translated to <code><distribution-root-dir>/suggestedsites/res/xhdpi/distroimage.png</code> on a XHDPI device.

The list of suggested sites from the distribution will be prepended to the default list of suggested sites that ships with Firefox.

=== Image Specs ===

When creating images for use in Suggested Sites, please use the following guidelines. Make sure you provide images for all the DPI levels or the thumbnail may not look good on some devices:

'''Images Sizes (Bounds)'''
* xxhdpi: 375x195
* xhdpi: 250x130
* hdpi: 188x98
* mdpi:125x65

== Testing a distribution locally ==
'''Note''': you need a clean install. If you have already run Firefox, go to settings and clear the app's data

=== APK distribution ===
* To create a repackaged distribution:
** For '''Firefox for Android 45 and later''':
*** Your distribution folder contents should be at:
***:<pre>/path/to/fennec-distribution-sample/assets/distribution</pre>
*** Add a line like the following to your mozconfig:
***:<pre>ac_add_options --with-android-distribution-directory=/path/to/fennec-distribution-sample</pre>
*** Make sure you have run <code>./mach configure</code> before building and packaging
*** See {{bug|1163082}} for details.
*** '''Note''': By default the distribution is going into the [https://gecko.readthedocs.io/en/latest/mobile/android/fennec/bouncer.html install bouncer APK]. To change that set ''MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER'' to ''False'' in ''mobile/android/moz.configure'' (See {{bug|1258372}} for details) or add ''export MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER='' to mozconfig in Firefox 50 or later.
** For '''Firefox for Android 44 and earlier''':
*** Put your distribution folder at <code>objdir/dist/bin/distribution</code>
*** Run <code>./mach package</code> to package the app
** When the app is launched, the distribution files will be copied out to <code>/data/data/org.mozilla.fennec_yourname/distribution</code>, and they will override a ROM image distribution if it is present

=== System distribution ===
* To create a ROM image distribution, follow these steps with a rooted phone:
** Copy the distribution files to a writable location
adb shell mkdir /data/local/tmp/distribution
adb push distribution /data/local/tmp/distribution
** Run <code>adb shell</code> to get and adb shell
$ su
# mount
# mount -o rw,remount /system
# cp -r /data/local/tmp/distribution /system/<package>/ # (replace <package> with the ID for the package you want to test, e.g. org.mozilla.firefox or org.mozilla.fennec)

==Testing distribution download==
A distribution download is triggered when two things are true:

* This is the first run of Firefox (or Clear Data has been used).
* An <code>INSTALL_REFERRER</code> intent has been received prior to launch.

The Google Play app takes care of sending that intent. You can also manually send it via <code>adb shell</code>. Assuming you're testing Nightly:

<pre>
am broadcast -a com.android.vending.INSTALL_REFERRER \
-n org.mozilla.firefox/org.mozilla.gecko.distribution.ReferrerReceiver \
-f 32 \
--es "referrer" "utm_source=mozilla\&utm_content=testsigned\&utm_campaign=distribution"
</pre>

This will fetch the "testsigned.jar" distribution.

(The -f 32 flag makes sure this intent is sent to stopped packages.)

You can also do this from another Android application:
<pre>
Intent i = new Intent("com.android.vending.INSTALL_REFERRER");
i.setPackage("org.mozilla.firefox");
i.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
i.putExtra("referrer", "utm_source=mozilla&utm_content=testsigned&utm_campaign=distribution");
getContext().sendBroadcast(i);
</pre>

Telemetry will be recorded for the download: <code>FENNEC_DISTRIBUTION_DOWNLOAD_TIME_MS</code> records the download time in milliseconds, and <code>FENNEC_DISTRIBUTION_CODE_CATEGORY</code> records the result. The value will be one of these:

; 0: Unexpected HTTP status.
; 1: HTTP 1xx. Should not occur.
; 2: HTTP 2xx. The expected result.
; 3: HTTP 3xx. Should not occur.
; 4: HTTP 4xx. Should not occur.
; 5: HTTP 5xx. Should not occur.
; 6: The device was offline.
; 7: Generic fetch exception.
; 8: Failure during processing of downloaded zip.
; 9: Security exception: malformed, corrupted, or modified signatures.
; 10: Malformed distribution file.
; 11: Fetch: socket error.
; 12: Fetch: SSL error.
; 13: Fetch: non-success HTTP response.
; 14: Fetch: invalid Content-Type header received.

==Crafting a distribution referrer==

These are the fields exposed in a referrer URL to Play:

; <code>utm_content</code>: '''The distribution name'''. Must be unique. Identifies the distribution name.
; <code>utm_campaign</code>: '''The campaign name'''. Must be <code>distribution</code>.
; <code>utm_source</code>: Original referrer. Must be <code>mozilla</code> for both downloadable distributions and campaign tracking.
; <code>utm_medium</code>: Campaign medium. E.g., <code>email</code>. Not used by Firefox.
; <code>utm_term</code>: Search terms. E.g., <code>web+browser</code>. Not used by Firefox.

== Distribution bundles ==

Firefox for Android 46.0 introduced support for distribution bundles based on the '''MCC''' (mobile country code, [https://en.wikipedia.org/wiki/Mobile_country_code]) and '''MNC''' (mobile network code) codes of the inserted SIM card. Instead of the default distribution directory Firefox will search a distribution in the following sub directories first:
* (distribution directory)/''<MCC>''/''<MNC>'' - For bundled distributions for specific network providers
* (distribution directory)/''<MCC>'' - For bundled distributions for specific countries
* (distribution directory)/''default'' - For bundled distributions with no matching MCC/MNC

=== Example distribution bundle ===
distribution
├── 208 // 208 = Country code of France
│   └── bookmarks.json // Bookmarks just for users with a SIM card of a French operator
├── 262 // 262 = Country code of Germany
│   └── 01 // 01 = Network code of "Deutsche Telekom"
│   ├── bookmarks.json // Bookmarks..
│   └── preferences.json // ... and preferences just for users of a SIM card of "Deutsche Telekom"
└── default // Default folder
└── preferences.json // Preferences for all users with different SIM cards.

== Partner Content Providers ==

Android system images can ship with two content providers to customize installed browsers:
* content://com.android.partnerbookmarks - For partner bookmarks
* content://com.android.partnerbrowsercustomizations - For customizations (Details see below)

Firefox for Android supports reading data from both of those content providers (Starting with Firefox for Android 50.0) if this has been enabled by a distribution. If the following preferences are not written by a distribution then Firefox for Android will ignore the data from the partner content providers.

''/distribution/preferences.json:''
<pre>
[..]
"AndroidPreferences": {
"distribution.read_partner_bookmarks_provider": true,
"distribution.read_partner_customizations_provider": true
}
[..]
</pre>

=== Bookmarks Content Provider ===

Firefox for Android (>= 50.0) supports reading bookmarks and folders from the content provider. Reading icons from the content provider is currently not supported (See {{bug|1286203}}). Editing and deleting bookmarks/folders is not supported yet but planned.

An example implementation of the content provider can be found in the official Android source tree:
* https://android.googlesource.com/platform/packages/providers/PartnerBookmarksProvider/+/master/src/com/android/providers/partnerbookmarks/PartnerBookmarksProvider.java

=== Customizations Content Provider ===

Firefox for Android (>= 50.0) only supports reading the 'homepage' from the content provider. All other values are ignored.

content://com.android.partnerbrowsercustomizations

{| class="wikitable"
|-
! Path !! Column !! Supported
|-
| /homepage || homepage || Yes
|-
| /disableincognitomode || disableincognitomode || No
|-
| /disablebookmarksediting || disablebookmarksediting || No
|}

=== Testing ===

There's a test app with sample data available on GitHub:
* https://github.com/pocmo/BrowserPartner

The test app uses slightly different content provider authorities to allow being installed on devices that already ship with partner content providers:

* com.android.partnerbookmarks.'''''test'''''
* com.android.partnerbrowsercustomizations.'''''test'''''

A custom Firefox build is required to read from the test content providers.

Mobile/Distribution Files

2017-04-06T08:39:23Z

Nevin: Bug 1293713 - update the pref name

Like [https://wiki.mozilla.org/Distribution_INI_File desktop], mobile Firefox supplies a way for partners to repackage a set of customization files into a Firefox build without recompiling. We don't want to make custom binary builds that need to be QA'd extensively. The "distribution files" concept allows a small set of external files to be used to customize a standard Firefox build. Things that can be customized include:
* Default bookmarks
* Preferences
* Lightweight themes
* Search engines
* Add-ons
* Quickshare defaults
* Suggested sites

A sample distribution directory is available on [https://github.com/mozilla/fennec-distribution-sample github].

==Overview==
There are currently three ways distribution files can be ... distributed:
# '''<big>APK distributions</big>''': A folder of distribution files is repackaged into the Android APK. During the first run, those files are extracted from the APK and stored in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory.
# '''<big>System distributions</big>''': A folder of distribution files are shipped with the ROM image in <code>/system/org.mozilla.firefox/distribution/*</code> directory. Shipping in this way ensures the files are not easily overwritten or removed by an application update. Note, files found in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory will "win" in cases where both locations are used.
# '''<big>Over-the-air distributions</big>''': A distribution zip file is downloaded over-the-air as a result of a post-install referrer intent. See {{bug|1013024}}. This feature should ship with Firefox 33.

Distributions are processed asynchronously during first run. Frontend code can chain post-distribution tasks via <code>Distribution.addOnDistributionReadyCallback</code>.

Each type of data has its own nuances:
* Default bookmarks are read from the APK directly or from the "distribution" folder (if it already exists) any time a profile is created. These bookmarks are created prior to Firefox's default bookmarks.
* Preferences are set as "default" preferences on each run, since a "default" preference only lasts for the lifetime of the session. They are created as "default" preferences to allow "user" preferences to override them.
* Lightweight themes are actually just preferences. The data for the theme must live online somewhere. Typical places are the AMO theme or getpersonas.com sites.
* Search engine plugins and add-ons must follow a fixed folder layout.
* If distribution data is processed after the initial quickshare set is loaded, these options won't take effect until next run ({{bug|1021176}}).

==Bookmarks==
Default bookmarks are specified in '''/distribution/bookmarks.json'''. This file should contain an array of bookmark JSON objects with the following properties:
* '''title''': (required) string for the bookmark title
* '''url''': (required) string for the bookmark URL
* title.<locale>: (optional) title string for the given locale
* url.<locale>: (optional) URL string for the given locale
* icon: (optional) data URI for the bookmark favicon
* pinned: (optional) boolean for whether or not to pin this bookmark to the about:home top sites
** NOTE: If a bookmark is pinned, it is not visible in the Bookmarks list. Pinning only affects Tops Sites.

Here is an example bookmarks.json:
[
{
"title": "Queso",
"url": "http://queso.com/",
"title.en_US": "Cheese",
"url.en_US": "http://cheese.com",
"icon": "data:image/png;base64,..."
}
]

==Preferences==
Preferences are specified in '''/distribution/preferences.json'''. This file should contain a JSON object with the following properties:
* Global
** '''id''': (required) a short string unique to this distribution
** '''version''': (required) version of the distribution (not the version of Firefox)
** '''about''': (required) a short descriptive (ui-visible) string for this distribution
** about.<locale>: (optional) descriptive string for the given locale
* Preferences (optional)
** This sets default Gecko preferences for the profile (i.e. prefs that would appear in about:config)
* LocalizablePreferences (optional)
* LocalizablePreferences.<locale> (optional)
* ApplicationPreferences (optional)
** This sets as the app-scoped SharedPreferences for the entire application. Since GeckoPreferenceFragment only accept application-scoped sharedPreferences, this object will let partner also have the ability to override them.
* AndroidPreferences (optional)
** This sets Android SharedPreferences for the profile

Here is an example preferences.json:
{
"Global": {
"id": "testpartner",
"version": 1.0,
"about": "Afiliado de Prueba",
"about.en-US": "Test Partner"
},
"Preferences": {
"distribution.test.string": "a string pref",
"distribution.test.boolean": true,
"distribution.test.int": 5
},
"LocalizablePreferences": {
"distribution.test.localizeable": "http://test.org/%LOCALE%/%LOCALE%/",
"distribution.test.localizeable-override": "http://test.org/%LOCALE%/%LOCALE%/"
},
"LocalizablePreferences.en-US": {
"distribution.test.localizeable-override": "http://cheese.com"
},
"AnpplicationPreferences": {
"newtab.load_homepage": "true"
}
"AndroidPreferences": {
"homepage": "http://www.mozilla.com"
}
}

==Lightweight Themes==
Lightweight themes are specified in the "Preferences" section of /distribution/preferences.json. Here is an example of the lightweight theme preferences needed for this to work:

"Preferences": {
"lightweightThemes.isThemeSelected": true,
"lightweightThemes.persisted.footerURL": false,
"lightweightThemes.persisted.headerURL": false,
"lightweightThemes.usedThemes": "[{\"id\":\"491717\",\"name\":\"colored trees\",\"headerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees.png?1358076678\",\"footerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees-base.png?1358076678\",\"textcolor\":\"#1d022b\",\"accentcolor\":\"#000000\",\"iconURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview_small.jpg?1358076678\",\"previewURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview.jpg?1358076678\",\"author\":\"birdyann\",\"description\":\"trees arbres colored colors couleurs\",\"updateURL\":\"https://www.getpersonas.com/en-US/update_check/491717\",\"version\":\"1358076678\",\"updateDate\":1359579038207,\"installDate\":1359579038207}]"
}

==Search Plugins==
Include search plugins in a directory structure like the following, and they will be
automatically loaded:

* distribution/
* searchplugins/
* common/
* <plugin.xml>
* <plugin.xml>
* ...
* locale/
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...

If a directory for the locale the browser is running in doesn't exist, Firefox will automatically try the 'default' locale, as defined by the <code>distribution.searchplugins.defaultLocale</code> preference.

To set a given search engine as the default, you need to use <code>LocalizablePreferences</code> to override the <code>browser.search.defaultenginename</code> preference. You should also override the <code>browser.search.order.1</code> preference to put the default engine in the right sort order. For example:

{
...
"LocalizablePreferences": {
"browser.search.defaultenginename": "<name-of-engine>",
"browser.search.order.1": "<name-of-engine>"
...
}
...
}

==Add-ons==
Include add-ons in an extensions directory as follows, and they will be
automatically loaded:

* distribution/
* extensions/
* someaddon@somedomain.com.xpi
* ...

Be sure to name the add-on XPI with the ID that's specified in the add-on's install.rdf.

'''Note:''' As of Firefox 41, we require all add-ons to be signed through AMO, so you should make sure this XPI is signed properly before shipping in a distribution.

==Quickshare defaults==
Add a file named <code>history.xml</code> under <code>distribution/quickshare</code>. Its contents should be something like:

<pre>
<historical-records>
<historical-record activity="com.android.mms/com.android.mms.ui.ConversationComposer"
time="0"
weight="1"/>
</historical-records>
</pre>

==Suggested sites==
Added by {{bug|1012462}} in Firefox 33.

Use a directory tree like the following. Locales are named via a locale code, such as <code>en-US</code>.

* distribution/
* suggestedsites/
* locales/
* <locale>/
* suggestedsites.json
* res/
* hdpi/
* <distro>.png
* xxhdpi/
* <distro>.png

The suggestedsites.json file should be a JSON array:

[
{
url: "<site-url>",
title: "<site-title>",
imageurl: "gecko.distribution://<image-dir>/<image-name>",
bgcolor: "<color-hex-code>", /* "#FF00FF" with leading '#' */
trackingid: <tiles-id> /* optional integer */
},
...
]

Where <code><image-dir></code> is the directory containing the density-specific image directories (<code>mdpi</code>, <code>hdpi</code>, etc) and <code><image-name></code> is the filename under the density-specific directories without the file extension. For example, <code>gecko.distribution://suggestedsites/res/distroimage</code> image URL will be translated to <code><distribution-root-dir>/suggestedsites/res/xhdpi/distroimage.png</code> on a XHDPI device.

The list of suggested sites from the distribution will be prepended to the default list of suggested sites that ships with Firefox.

=== Image Specs ===

When creating images for use in Suggested Sites, please use the following guidelines. Make sure you provide images for all the DPI levels or the thumbnail may not look good on some devices:

'''Images Sizes (Bounds)'''
* xxhdpi: 375x195
* xhdpi: 250x130
* hdpi: 188x98
* mdpi:125x65

== Testing a distribution locally ==
'''Note''': you need a clean install. If you have already run Firefox, go to settings and clear the app's data

=== APK distribution ===
* To create a repackaged distribution:
** For '''Firefox for Android 45 and later''':
*** Your distribution folder contents should be at:
***:<pre>/path/to/fennec-distribution-sample/assets/distribution</pre>
*** Add a line like the following to your mozconfig:
***:<pre>ac_add_options --with-android-distribution-directory=/path/to/fennec-distribution-sample</pre>
*** Make sure you have run <code>./mach configure</code> before building and packaging
*** See {{bug|1163082}} for details.
*** '''Note''': By default the distribution is going into the [https://gecko.readthedocs.io/en/latest/mobile/android/fennec/bouncer.html install bouncer APK]. To change that set ''MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER'' to ''False'' in ''mobile/android/moz.configure'' (See {{bug|1258372}} for details) or add ''export MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER='' to mozconfig in Firefox 50 or later.
** For '''Firefox for Android 44 and earlier''':
*** Put your distribution folder at <code>objdir/dist/bin/distribution</code>
*** Run <code>./mach package</code> to package the app
** When the app is launched, the distribution files will be copied out to <code>/data/data/org.mozilla.fennec_yourname/distribution</code>, and they will override a ROM image distribution if it is present

=== System distribution ===
* To create a ROM image distribution, follow these steps with a rooted phone:
** Copy the distribution files to a writable location
adb shell mkdir /data/local/tmp/distribution
adb push distribution /data/local/tmp/distribution
** Run <code>adb shell</code> to get and adb shell
$ su
# mount
# mount -o rw,remount /system
# cp -r /data/local/tmp/distribution /system/<package>/ # (replace <package> with the ID for the package you want to test, e.g. org.mozilla.firefox or org.mozilla.fennec)

==Testing distribution download==
A distribution download is triggered when two things are true:

* This is the first run of Firefox (or Clear Data has been used).
* An <code>INSTALL_REFERRER</code> intent has been received prior to launch.

The Google Play app takes care of sending that intent. You can also manually send it via <code>adb shell</code>. Assuming you're testing Nightly:

<pre>
am broadcast -a com.android.vending.INSTALL_REFERRER \
-n org.mozilla.firefox/org.mozilla.gecko.distribution.ReferrerReceiver \
-f 32 \
--es "referrer" "utm_source=mozilla\&utm_content=testsigned\&utm_campaign=distribution"
</pre>

This will fetch the "testsigned.jar" distribution.

(The -f 32 flag makes sure this intent is sent to stopped packages.)

You can also do this from another Android application:
<pre>
Intent i = new Intent("com.android.vending.INSTALL_REFERRER");
i.setPackage("org.mozilla.firefox");
i.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
i.putExtra("referrer", "utm_source=mozilla&utm_content=testsigned&utm_campaign=distribution");
getContext().sendBroadcast(i);
</pre>

Telemetry will be recorded for the download: <code>FENNEC_DISTRIBUTION_DOWNLOAD_TIME_MS</code> records the download time in milliseconds, and <code>FENNEC_DISTRIBUTION_CODE_CATEGORY</code> records the result. The value will be one of these:

; 0: Unexpected HTTP status.
; 1: HTTP 1xx. Should not occur.
; 2: HTTP 2xx. The expected result.
; 3: HTTP 3xx. Should not occur.
; 4: HTTP 4xx. Should not occur.
; 5: HTTP 5xx. Should not occur.
; 6: The device was offline.
; 7: Generic fetch exception.
; 8: Failure during processing of downloaded zip.
; 9: Security exception: malformed, corrupted, or modified signatures.
; 10: Malformed distribution file.
; 11: Fetch: socket error.
; 12: Fetch: SSL error.
; 13: Fetch: non-success HTTP response.
; 14: Fetch: invalid Content-Type header received.

==Crafting a distribution referrer==

These are the fields exposed in a referrer URL to Play:

; <code>utm_content</code>: '''The distribution name'''. Must be unique. Identifies the distribution name.
; <code>utm_campaign</code>: '''The campaign name'''. Must be <code>distribution</code>.
; <code>utm_source</code>: Original referrer. Must be <code>mozilla</code> for both downloadable distributions and campaign tracking.
; <code>utm_medium</code>: Campaign medium. E.g., <code>email</code>. Not used by Firefox.
; <code>utm_term</code>: Search terms. E.g., <code>web+browser</code>. Not used by Firefox.

== Distribution bundles ==

Firefox for Android 46.0 introduced support for distribution bundles based on the '''MCC''' (mobile country code, [https://en.wikipedia.org/wiki/Mobile_country_code]) and '''MNC''' (mobile network code) codes of the inserted SIM card. Instead of the default distribution directory Firefox will search a distribution in the following sub directories first:
* (distribution directory)/''<MCC>''/''<MNC>'' - For bundled distributions for specific network providers
* (distribution directory)/''<MCC>'' - For bundled distributions for specific countries
* (distribution directory)/''default'' - For bundled distributions with no matching MCC/MNC

=== Example distribution bundle ===
distribution
├── 208 // 208 = Country code of France
│   └── bookmarks.json // Bookmarks just for users with a SIM card of a French operator
├── 262 // 262 = Country code of Germany
│   └── 01 // 01 = Network code of "Deutsche Telekom"
│   ├── bookmarks.json // Bookmarks..
│   └── preferences.json // ... and preferences just for users of a SIM card of "Deutsche Telekom"
└── default // Default folder
└── preferences.json // Preferences for all users with different SIM cards.

== Partner Content Providers ==

Android system images can ship with two content providers to customize installed browsers:
* content://com.android.partnerbookmarks - For partner bookmarks
* content://com.android.partnerbrowsercustomizations - For customizations (Details see below)

Firefox for Android supports reading data from both of those content providers (Starting with Firefox for Android 50.0) if this has been enabled by a distribution. If the following preferences are not written by a distribution then Firefox for Android will ignore the data from the partner content providers.

''/distribution/preferences.json:''
<pre>
[..]
"AndroidPreferences": {
"distribution.read_partner_bookmarks_provider": true,
"distribution.read_partner_customizations_provider": true
}
[..]
</pre>

=== Bookmarks Content Provider ===

Firefox for Android (>= 50.0) supports reading bookmarks and folders from the content provider. Reading icons from the content provider is currently not supported (See {{bug|1286203}}). Editing and deleting bookmarks/folders is not supported yet but planned.

An example implementation of the content provider can be found in the official Android source tree:
* https://android.googlesource.com/platform/packages/providers/PartnerBookmarksProvider/+/master/src/com/android/providers/partnerbookmarks/PartnerBookmarksProvider.java

=== Customizations Content Provider ===

Firefox for Android (>= 50.0) only supports reading the 'homepage' from the content provider. All other values are ignored.

content://com.android.partnerbrowsercustomizations

{| class="wikitable"
|-
! Path !! Column !! Supported
|-
| /homepage || homepage || Yes
|-
| /disableincognitomode || disableincognitomode || No
|-
| /disablebookmarksediting || disablebookmarksediting || No
|}

=== Testing ===

There's a test app with sample data available on GitHub:
* https://github.com/pocmo/BrowserPartner

The test app uses slightly different content provider authorities to allow being installed on devices that already ship with partner content providers:

* com.android.partnerbookmarks.'''''test'''''
* com.android.partnerbrowsercustomizations.'''''test'''''

A custom Firefox build is required to read from the test content providers.

Mobile/Distribution Files

2017-03-23T14:21:37Z

Nevin: Bug 1295675 - Allow for the setting of application level preferences from a distribution

Like [https://wiki.mozilla.org/Distribution_INI_File desktop], mobile Firefox supplies a way for partners to repackage a set of customization files into a Firefox build without recompiling. We don't want to make custom binary builds that need to be QA'd extensively. The "distribution files" concept allows a small set of external files to be used to customize a standard Firefox build. Things that can be customized include:
* Default bookmarks
* Preferences
* Lightweight themes
* Search engines
* Add-ons
* Quickshare defaults
* Suggested sites

A sample distribution directory is available on [https://github.com/mozilla/fennec-distribution-sample github].

==Overview==
There are currently three ways distribution files can be ... distributed:
# '''<big>APK distributions</big>''': A folder of distribution files is repackaged into the Android APK. During the first run, those files are extracted from the APK and stored in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory.
# '''<big>System distributions</big>''': A folder of distribution files are shipped with the ROM image in <code>/system/org.mozilla.firefox/distribution/*</code> directory. Shipping in this way ensures the files are not easily overwritten or removed by an application update. Note, files found in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory will "win" in cases where both locations are used.
# '''<big>Over-the-air distributions</big>''': A distribution zip file is downloaded over-the-air as a result of a post-install referrer intent. See {{bug|1013024}}. This feature should ship with Firefox 33.

Distributions are processed asynchronously during first run. Frontend code can chain post-distribution tasks via <code>Distribution.addOnDistributionReadyCallback</code>.

Each type of data has its own nuances:
* Default bookmarks are read from the APK directly or from the "distribution" folder (if it already exists) any time a profile is created. These bookmarks are created prior to Firefox's default bookmarks.
* Preferences are set as "default" preferences on each run, since a "default" preference only lasts for the lifetime of the session. They are created as "default" preferences to allow "user" preferences to override them.
* Lightweight themes are actually just preferences. The data for the theme must live online somewhere. Typical places are the AMO theme or getpersonas.com sites.
* Search engine plugins and add-ons must follow a fixed folder layout.
* If distribution data is processed after the initial quickshare set is loaded, these options won't take effect until next run ({{bug|1021176}}).

==Bookmarks==
Default bookmarks are specified in '''/distribution/bookmarks.json'''. This file should contain an array of bookmark JSON objects with the following properties:
* '''title''': (required) string for the bookmark title
* '''url''': (required) string for the bookmark URL
* title.<locale>: (optional) title string for the given locale
* url.<locale>: (optional) URL string for the given locale
* icon: (optional) data URI for the bookmark favicon
* pinned: (optional) boolean for whether or not to pin this bookmark to the about:home top sites
** NOTE: If a bookmark is pinned, it is not visible in the Bookmarks list. Pinning only affects Tops Sites.

Here is an example bookmarks.json:
[
{
"title": "Queso",
"url": "http://queso.com/",
"title.en_US": "Cheese",
"url.en_US": "http://cheese.com",
"icon": "data:image/png;base64,..."
}
]

==Preferences==
Preferences are specified in '''/distribution/preferences.json'''. This file should contain a JSON object with the following properties:
* Global
** '''id''': (required) a short string unique to this distribution
** '''version''': (required) version of the distribution (not the version of Firefox)
** '''about''': (required) a short descriptive (ui-visible) string for this distribution
** about.<locale>: (optional) descriptive string for the given locale
* Preferences (optional)
** This sets default Gecko preferences for the profile (i.e. prefs that would appear in about:config)
* LocalizablePreferences (optional)
* LocalizablePreferences.<locale> (optional)
* ApplicationPreferences (optional)
** This sets as the app-scoped SharedPreferences for the entire application. Since GeckoPreferenceFragment only accept application-scoped sharedPreferences, this object will let partner also have the ability to override them.
* AndroidPreferences (optional)
** This sets Android SharedPreferences for the profile

Here is an example preferences.json:
{
"Global": {
"id": "testpartner",
"version": 1.0,
"about": "Afiliado de Prueba",
"about.en-US": "Test Partner"
},
"Preferences": {
"distribution.test.string": "a string pref",
"distribution.test.boolean": true,
"distribution.test.int": 5
},
"LocalizablePreferences": {
"distribution.test.localizeable": "http://test.org/%LOCALE%/%LOCALE%/",
"distribution.test.localizeable-override": "http://test.org/%LOCALE%/%LOCALE%/"
},
"LocalizablePreferences.en-US": {
"distribution.test.localizeable-override": "http://cheese.com"
},
"AnpplicationPreferences": {
"homepage.for.new.tab.enabled": "true"
}
"AndroidPreferences": {
"homepage": "http://www.mozilla.com"
}
}

==Lightweight Themes==
Lightweight themes are specified in the "Preferences" section of /distribution/preferences.json. Here is an example of the lightweight theme preferences needed for this to work:

"Preferences": {
"lightweightThemes.isThemeSelected": true,
"lightweightThemes.persisted.footerURL": false,
"lightweightThemes.persisted.headerURL": false,
"lightweightThemes.usedThemes": "[{\"id\":\"491717\",\"name\":\"colored trees\",\"headerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees.png?1358076678\",\"footerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees-base.png?1358076678\",\"textcolor\":\"#1d022b\",\"accentcolor\":\"#000000\",\"iconURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview_small.jpg?1358076678\",\"previewURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview.jpg?1358076678\",\"author\":\"birdyann\",\"description\":\"trees arbres colored colors couleurs\",\"updateURL\":\"https://www.getpersonas.com/en-US/update_check/491717\",\"version\":\"1358076678\",\"updateDate\":1359579038207,\"installDate\":1359579038207}]"
}

==Search Plugins==
Include search plugins in a directory structure like the following, and they will be
automatically loaded:

* distribution/
* searchplugins/
* common/
* <plugin.xml>
* <plugin.xml>
* ...
* locale/
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...

If a directory for the locale the browser is running in doesn't exist, Firefox will automatically try the 'default' locale, as defined by the <code>distribution.searchplugins.defaultLocale</code> preference.

To set a given search engine as the default, you need to use <code>LocalizablePreferences</code> to override the <code>browser.search.defaultenginename</code> preference. You should also override the <code>browser.search.order.1</code> preference to put the default engine in the right sort order. For example:

{
...
"LocalizablePreferences": {
"browser.search.defaultenginename": "<name-of-engine>",
"browser.search.order.1": "<name-of-engine>"
...
}
...
}

==Add-ons==
Include add-ons in an extensions directory as follows, and they will be
automatically loaded:

* distribution/
* extensions/
* someaddon@somedomain.com.xpi
* ...

Be sure to name the add-on XPI with the ID that's specified in the add-on's install.rdf.

'''Note:''' As of Firefox 41, we require all add-ons to be signed through AMO, so you should make sure this XPI is signed properly before shipping in a distribution.

==Quickshare defaults==
Add a file named <code>history.xml</code> under <code>distribution/quickshare</code>. Its contents should be something like:

<pre>
<historical-records>
<historical-record activity="com.android.mms/com.android.mms.ui.ConversationComposer"
time="0"
weight="1"/>
</historical-records>
</pre>

==Suggested sites==
Added by {{bug|1012462}} in Firefox 33.

Use a directory tree like the following. Locales are named via a locale code, such as <code>en-US</code>.

* distribution/
* suggestedsites/
* locales/
* <locale>/
* suggestedsites.json
* res/
* hdpi/
* <distro>.png
* xxhdpi/
* <distro>.png

The suggestedsites.json file should be a JSON array:

[
{
url: "<site-url>",
title: "<site-title>",
imageurl: "gecko.distribution://<image-dir>/<image-name>",
bgcolor: "<color-hex-code>", /* "#FF00FF" with leading '#' */
trackingid: <tiles-id> /* optional integer */
},
...
]

Where <code><image-dir></code> is the directory containing the density-specific image directories (<code>mdpi</code>, <code>hdpi</code>, etc) and <code><image-name></code> is the filename under the density-specific directories without the file extension. For example, <code>gecko.distribution://suggestedsites/res/distroimage</code> image URL will be translated to <code><distribution-root-dir>/suggestedsites/res/xhdpi/distroimage.png</code> on a XHDPI device.

The list of suggested sites from the distribution will be prepended to the default list of suggested sites that ships with Firefox.

=== Image Specs ===

When creating images for use in Suggested Sites, please use the following guidelines. Make sure you provide images for all the DPI levels or the thumbnail may not look good on some devices:

'''Images Sizes (Bounds)'''
* xxhdpi: 375x195
* xhdpi: 250x130
* hdpi: 188x98
* mdpi:125x65

== Testing a distribution locally ==
'''Note''': you need a clean install. If you have already run Firefox, go to settings and clear the app's data

=== APK distribution ===
* To create a repackaged distribution:
** For '''Firefox for Android 45 and later''':
*** Your distribution folder contents should be at:
***:<pre>/path/to/fennec-distribution-sample/assets/distribution</pre>
*** Add a line like the following to your mozconfig:
***:<pre>ac_add_options --with-android-distribution-directory=/path/to/fennec-distribution-sample</pre>
*** Make sure you have run <code>./mach configure</code> before building and packaging
*** See {{bug|1163082}} for details.
*** '''Note''': By default the distribution is going into the [https://gecko.readthedocs.io/en/latest/mobile/android/fennec/bouncer.html install bouncer APK]. To change that set ''MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER'' to ''False'' in ''mobile/android/moz.configure'' (See {{bug|1258372}} for details) or add ''export MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER='' to mozconfig in Firefox 50 or later.
** For '''Firefox for Android 44 and earlier''':
*** Put your distribution folder at <code>objdir/dist/bin/distribution</code>
*** Run <code>./mach package</code> to package the app
** When the app is launched, the distribution files will be copied out to <code>/data/data/org.mozilla.fennec_yourname/distribution</code>, and they will override a ROM image distribution if it is present

=== System distribution ===
* To create a ROM image distribution, follow these steps with a rooted phone:
** Copy the distribution files to a writable location
adb shell mkdir /data/local/tmp/distribution
adb push distribution /data/local/tmp/distribution
** Run <code>adb shell</code> to get and adb shell
$ su
# mount
# mount -o rw,remount /system
# cp -r /data/local/tmp/distribution /system/<package>/ # (replace <package> with the ID for the package you want to test, e.g. org.mozilla.firefox or org.mozilla.fennec)

==Testing distribution download==
A distribution download is triggered when two things are true:

* This is the first run of Firefox (or Clear Data has been used).
* An <code>INSTALL_REFERRER</code> intent has been received prior to launch.

The Google Play app takes care of sending that intent. You can also manually send it via <code>adb shell</code>. Assuming you're testing Nightly:

<pre>
am broadcast -a com.android.vending.INSTALL_REFERRER \
-n org.mozilla.firefox/org.mozilla.gecko.distribution.ReferrerReceiver \
-f 32 \
--es "referrer" "utm_source=mozilla\&utm_content=testsigned\&utm_campaign=distribution"
</pre>

This will fetch the "testsigned.jar" distribution.

(The -f 32 flag makes sure this intent is sent to stopped packages.)

You can also do this from another Android application:
<pre>
Intent i = new Intent("com.android.vending.INSTALL_REFERRER");
i.setPackage("org.mozilla.firefox");
i.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
i.putExtra("referrer", "utm_source=mozilla&utm_content=testsigned&utm_campaign=distribution");
getContext().sendBroadcast(i);
</pre>

Telemetry will be recorded for the download: <code>FENNEC_DISTRIBUTION_DOWNLOAD_TIME_MS</code> records the download time in milliseconds, and <code>FENNEC_DISTRIBUTION_CODE_CATEGORY</code> records the result. The value will be one of these:

; 0: Unexpected HTTP status.
; 1: HTTP 1xx. Should not occur.
; 2: HTTP 2xx. The expected result.
; 3: HTTP 3xx. Should not occur.
; 4: HTTP 4xx. Should not occur.
; 5: HTTP 5xx. Should not occur.
; 6: The device was offline.
; 7: Generic fetch exception.
; 8: Failure during processing of downloaded zip.
; 9: Security exception: malformed, corrupted, or modified signatures.
; 10: Malformed distribution file.
; 11: Fetch: socket error.
; 12: Fetch: SSL error.
; 13: Fetch: non-success HTTP response.
; 14: Fetch: invalid Content-Type header received.

==Crafting a distribution referrer==

These are the fields exposed in a referrer URL to Play:

; <code>utm_content</code>: '''The distribution name'''. Must be unique. Identifies the distribution name.
; <code>utm_campaign</code>: '''The campaign name'''. Must be <code>distribution</code>.
; <code>utm_source</code>: Original referrer. Must be <code>mozilla</code> for both downloadable distributions and campaign tracking.
; <code>utm_medium</code>: Campaign medium. E.g., <code>email</code>. Not used by Firefox.
; <code>utm_term</code>: Search terms. E.g., <code>web+browser</code>. Not used by Firefox.

== Distribution bundles ==

Firefox for Android 46.0 introduced support for distribution bundles based on the '''MCC''' (mobile country code, [https://en.wikipedia.org/wiki/Mobile_country_code]) and '''MNC''' (mobile network code) codes of the inserted SIM card. Instead of the default distribution directory Firefox will search a distribution in the following sub directories first:
* (distribution directory)/''<MCC>''/''<MNC>'' - For bundled distributions for specific network providers
* (distribution directory)/''<MCC>'' - For bundled distributions for specific countries
* (distribution directory)/''default'' - For bundled distributions with no matching MCC/MNC

=== Example distribution bundle ===
distribution
├── 208 // 208 = Country code of France
│   └── bookmarks.json // Bookmarks just for users with a SIM card of a French operator
├── 262 // 262 = Country code of Germany
│   └── 01 // 01 = Network code of "Deutsche Telekom"
│   ├── bookmarks.json // Bookmarks..
│   └── preferences.json // ... and preferences just for users of a SIM card of "Deutsche Telekom"
└── default // Default folder
└── preferences.json // Preferences for all users with different SIM cards.

== Partner Content Providers ==

Android system images can ship with two content providers to customize installed browsers:
* content://com.android.partnerbookmarks - For partner bookmarks
* content://com.android.partnerbrowsercustomizations - For customizations (Details see below)

Firefox for Android supports reading data from both of those content providers (Starting with Firefox for Android 50.0) if this has been enabled by a distribution. If the following preferences are not written by a distribution then Firefox for Android will ignore the data from the partner content providers.

''/distribution/preferences.json:''
<pre>
[..]
"AndroidPreferences": {
"distribution.read_partner_bookmarks_provider": true,
"distribution.read_partner_customizations_provider": true
}
[..]
</pre>

=== Bookmarks Content Provider ===

Firefox for Android (>= 50.0) supports reading bookmarks and folders from the content provider. Reading icons from the content provider is currently not supported (See {{bug|1286203}}). Editing and deleting bookmarks/folders is not supported yet but planned.

An example implementation of the content provider can be found in the official Android source tree:
* https://android.googlesource.com/platform/packages/providers/PartnerBookmarksProvider/+/master/src/com/android/providers/partnerbookmarks/PartnerBookmarksProvider.java

=== Customizations Content Provider ===

Firefox for Android (>= 50.0) only supports reading the 'homepage' from the content provider. All other values are ignored.

content://com.android.partnerbrowsercustomizations

{| class="wikitable"
|-
! Path !! Column !! Supported
|-
| /homepage || homepage || Yes
|-
| /disableincognitomode || disableincognitomode || No
|-
| /disablebookmarksediting || disablebookmarksediting || No
|}

=== Testing ===

There's a test app with sample data available on GitHub:
* https://github.com/pocmo/BrowserPartner

The test app uses slightly different content provider authorities to allow being installed on devices that already ship with partner content providers:

* com.android.partnerbookmarks.'''''test'''''
* com.android.partnerbrowsercustomizations.'''''test'''''

A custom Firefox build is required to read from the test content providers.

Mobile/Distribution Files

2017-03-23T14:10:17Z

Nevin: Bug 1295675 - Allow for the setting of application level preferences from a distribution

Like [https://wiki.mozilla.org/Distribution_INI_File desktop], mobile Firefox supplies a way for partners to repackage a set of customization files into a Firefox build without recompiling. We don't want to make custom binary builds that need to be QA'd extensively. The "distribution files" concept allows a small set of external files to be used to customize a standard Firefox build. Things that can be customized include:
* Default bookmarks
* Preferences
* Lightweight themes
* Search engines
* Add-ons
* Quickshare defaults
* Suggested sites

A sample distribution directory is available on [https://github.com/mozilla/fennec-distribution-sample github].

==Overview==
There are currently three ways distribution files can be ... distributed:
# '''<big>APK distributions</big>''': A folder of distribution files is repackaged into the Android APK. During the first run, those files are extracted from the APK and stored in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory.
# '''<big>System distributions</big>''': A folder of distribution files are shipped with the ROM image in <code>/system/org.mozilla.firefox/distribution/*</code> directory. Shipping in this way ensures the files are not easily overwritten or removed by an application update. Note, files found in the <code>/data/data/org.mozilla.firefox/distribution/*</code> directory will "win" in cases where both locations are used.
# '''<big>Over-the-air distributions</big>''': A distribution zip file is downloaded over-the-air as a result of a post-install referrer intent. See {{bug|1013024}}. This feature should ship with Firefox 33.

Distributions are processed asynchronously during first run. Frontend code can chain post-distribution tasks via <code>Distribution.addOnDistributionReadyCallback</code>.

Each type of data has its own nuances:
* Default bookmarks are read from the APK directly or from the "distribution" folder (if it already exists) any time a profile is created. These bookmarks are created prior to Firefox's default bookmarks.
* Preferences are set as "default" preferences on each run, since a "default" preference only lasts for the lifetime of the session. They are created as "default" preferences to allow "user" preferences to override them.
* Lightweight themes are actually just preferences. The data for the theme must live online somewhere. Typical places are the AMO theme or getpersonas.com sites.
* Search engine plugins and add-ons must follow a fixed folder layout.
* If distribution data is processed after the initial quickshare set is loaded, these options won't take effect until next run ({{bug|1021176}}).

==Bookmarks==
Default bookmarks are specified in '''/distribution/bookmarks.json'''. This file should contain an array of bookmark JSON objects with the following properties:
* '''title''': (required) string for the bookmark title
* '''url''': (required) string for the bookmark URL
* title.<locale>: (optional) title string for the given locale
* url.<locale>: (optional) URL string for the given locale
* icon: (optional) data URI for the bookmark favicon
* pinned: (optional) boolean for whether or not to pin this bookmark to the about:home top sites
** NOTE: If a bookmark is pinned, it is not visible in the Bookmarks list. Pinning only affects Tops Sites.

Here is an example bookmarks.json:
[
{
"title": "Queso",
"url": "http://queso.com/",
"title.en_US": "Cheese",
"url.en_US": "http://cheese.com",
"icon": "data:image/png;base64,..."
}
]

==Preferences==
Preferences are specified in '''/distribution/preferences.json'''. This file should contain a JSON object with the following properties:
* Global
** '''id''': (required) a short string unique to this distribution
** '''version''': (required) version of the distribution (not the version of Firefox)
** '''about''': (required) a short descriptive (ui-visible) string for this distribution
** about.<locale>: (optional) descriptive string for the given locale
* Preferences (optional)
** This sets default Gecko preferences for the profile (i.e. prefs that would appear in about:config)
* LocalizablePreferences (optional)
* LocalizablePreferences.<locale> (optional)
* ApplicationPreferences (optional)
* AndroidPreferences (optional)
** This sets Android SharedPreferences for the profile

Here is an example preferences.json:
{
"Global": {
"id": "testpartner",
"version": 1.0,
"about": "Afiliado de Prueba",
"about.en-US": "Test Partner"
},
"Preferences": {
"distribution.test.string": "a string pref",
"distribution.test.boolean": true,
"distribution.test.int": 5
},
"LocalizablePreferences": {
"distribution.test.localizeable": "http://test.org/%LOCALE%/%LOCALE%/",
"distribution.test.localizeable-override": "http://test.org/%LOCALE%/%LOCALE%/"
},
"LocalizablePreferences.en-US": {
"distribution.test.localizeable-override": "http://cheese.com"
},
"AnpplicationPreferences": {
"homepage.for.new.tab.enabled": "true"
}
"AndroidPreferences": {
"homepage": "http://www.mozilla.com"
}
}

==Lightweight Themes==
Lightweight themes are specified in the "Preferences" section of /distribution/preferences.json. Here is an example of the lightweight theme preferences needed for this to work:

"Preferences": {
"lightweightThemes.isThemeSelected": true,
"lightweightThemes.persisted.footerURL": false,
"lightweightThemes.persisted.headerURL": false,
"lightweightThemes.usedThemes": "[{\"id\":\"491717\",\"name\":\"colored trees\",\"headerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees.png?1358076678\",\"footerURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/trees-base.png?1358076678\",\"textcolor\":\"#1d022b\",\"accentcolor\":\"#000000\",\"iconURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview_small.jpg?1358076678\",\"previewURL\":\"http://getpersonas-cdn.mozilla.net/static/1/7/491717/preview.jpg?1358076678\",\"author\":\"birdyann\",\"description\":\"trees arbres colored colors couleurs\",\"updateURL\":\"https://www.getpersonas.com/en-US/update_check/491717\",\"version\":\"1358076678\",\"updateDate\":1359579038207,\"installDate\":1359579038207}]"
}

==Search Plugins==
Include search plugins in a directory structure like the following, and they will be
automatically loaded:

* distribution/
* searchplugins/
* common/
* <plugin.xml>
* <plugin.xml>
* ...
* locale/
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...
* <locale>/
* <plugin.xml>
* <plugin.xml>
* ...

If a directory for the locale the browser is running in doesn't exist, Firefox will automatically try the 'default' locale, as defined by the <code>distribution.searchplugins.defaultLocale</code> preference.

To set a given search engine as the default, you need to use <code>LocalizablePreferences</code> to override the <code>browser.search.defaultenginename</code> preference. You should also override the <code>browser.search.order.1</code> preference to put the default engine in the right sort order. For example:

{
...
"LocalizablePreferences": {
"browser.search.defaultenginename": "<name-of-engine>",
"browser.search.order.1": "<name-of-engine>"
...
}
...
}

==Add-ons==
Include add-ons in an extensions directory as follows, and they will be
automatically loaded:

* distribution/
* extensions/
* someaddon@somedomain.com.xpi
* ...

Be sure to name the add-on XPI with the ID that's specified in the add-on's install.rdf.

'''Note:''' As of Firefox 41, we require all add-ons to be signed through AMO, so you should make sure this XPI is signed properly before shipping in a distribution.

==Quickshare defaults==
Add a file named <code>history.xml</code> under <code>distribution/quickshare</code>. Its contents should be something like:

<pre>
<historical-records>
<historical-record activity="com.android.mms/com.android.mms.ui.ConversationComposer"
time="0"
weight="1"/>
</historical-records>
</pre>

==Suggested sites==
Added by {{bug|1012462}} in Firefox 33.

Use a directory tree like the following. Locales are named via a locale code, such as <code>en-US</code>.

* distribution/
* suggestedsites/
* locales/
* <locale>/
* suggestedsites.json
* res/
* hdpi/
* <distro>.png
* xxhdpi/
* <distro>.png

The suggestedsites.json file should be a JSON array:

[
{
url: "<site-url>",
title: "<site-title>",
imageurl: "gecko.distribution://<image-dir>/<image-name>",
bgcolor: "<color-hex-code>", /* "#FF00FF" with leading '#' */
trackingid: <tiles-id> /* optional integer */
},
...
]

Where <code><image-dir></code> is the directory containing the density-specific image directories (<code>mdpi</code>, <code>hdpi</code>, etc) and <code><image-name></code> is the filename under the density-specific directories without the file extension. For example, <code>gecko.distribution://suggestedsites/res/distroimage</code> image URL will be translated to <code><distribution-root-dir>/suggestedsites/res/xhdpi/distroimage.png</code> on a XHDPI device.

The list of suggested sites from the distribution will be prepended to the default list of suggested sites that ships with Firefox.

=== Image Specs ===

When creating images for use in Suggested Sites, please use the following guidelines. Make sure you provide images for all the DPI levels or the thumbnail may not look good on some devices:

'''Images Sizes (Bounds)'''
* xxhdpi: 375x195
* xhdpi: 250x130
* hdpi: 188x98
* mdpi:125x65

== Testing a distribution locally ==
'''Note''': you need a clean install. If you have already run Firefox, go to settings and clear the app's data

=== APK distribution ===
* To create a repackaged distribution:
** For '''Firefox for Android 45 and later''':
*** Your distribution folder contents should be at:
***:<pre>/path/to/fennec-distribution-sample/assets/distribution</pre>
*** Add a line like the following to your mozconfig:
***:<pre>ac_add_options --with-android-distribution-directory=/path/to/fennec-distribution-sample</pre>
*** Make sure you have run <code>./mach configure</code> before building and packaging
*** See {{bug|1163082}} for details.
*** '''Note''': By default the distribution is going into the [https://gecko.readthedocs.io/en/latest/mobile/android/fennec/bouncer.html install bouncer APK]. To change that set ''MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER'' to ''False'' in ''mobile/android/moz.configure'' (See {{bug|1258372}} for details) or add ''export MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER='' to mozconfig in Firefox 50 or later.
** For '''Firefox for Android 44 and earlier''':
*** Put your distribution folder at <code>objdir/dist/bin/distribution</code>
*** Run <code>./mach package</code> to package the app
** When the app is launched, the distribution files will be copied out to <code>/data/data/org.mozilla.fennec_yourname/distribution</code>, and they will override a ROM image distribution if it is present

=== System distribution ===
* To create a ROM image distribution, follow these steps with a rooted phone:
** Copy the distribution files to a writable location
adb shell mkdir /data/local/tmp/distribution
adb push distribution /data/local/tmp/distribution
** Run <code>adb shell</code> to get and adb shell
$ su
# mount
# mount -o rw,remount /system
# cp -r /data/local/tmp/distribution /system/<package>/ # (replace <package> with the ID for the package you want to test, e.g. org.mozilla.firefox or org.mozilla.fennec)

==Testing distribution download==
A distribution download is triggered when two things are true:

* This is the first run of Firefox (or Clear Data has been used).
* An <code>INSTALL_REFERRER</code> intent has been received prior to launch.

The Google Play app takes care of sending that intent. You can also manually send it via <code>adb shell</code>. Assuming you're testing Nightly:

<pre>
am broadcast -a com.android.vending.INSTALL_REFERRER \
-n org.mozilla.firefox/org.mozilla.gecko.distribution.ReferrerReceiver \
-f 32 \
--es "referrer" "utm_source=mozilla\&utm_content=testsigned\&utm_campaign=distribution"
</pre>

This will fetch the "testsigned.jar" distribution.

(The -f 32 flag makes sure this intent is sent to stopped packages.)

You can also do this from another Android application:
<pre>
Intent i = new Intent("com.android.vending.INSTALL_REFERRER");
i.setPackage("org.mozilla.firefox");
i.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES);
i.putExtra("referrer", "utm_source=mozilla&utm_content=testsigned&utm_campaign=distribution");
getContext().sendBroadcast(i);
</pre>

Telemetry will be recorded for the download: <code>FENNEC_DISTRIBUTION_DOWNLOAD_TIME_MS</code> records the download time in milliseconds, and <code>FENNEC_DISTRIBUTION_CODE_CATEGORY</code> records the result. The value will be one of these:

; 0: Unexpected HTTP status.
; 1: HTTP 1xx. Should not occur.
; 2: HTTP 2xx. The expected result.
; 3: HTTP 3xx. Should not occur.
; 4: HTTP 4xx. Should not occur.
; 5: HTTP 5xx. Should not occur.
; 6: The device was offline.
; 7: Generic fetch exception.
; 8: Failure during processing of downloaded zip.
; 9: Security exception: malformed, corrupted, or modified signatures.
; 10: Malformed distribution file.
; 11: Fetch: socket error.
; 12: Fetch: SSL error.
; 13: Fetch: non-success HTTP response.
; 14: Fetch: invalid Content-Type header received.

==Crafting a distribution referrer==

These are the fields exposed in a referrer URL to Play:

; <code>utm_content</code>: '''The distribution name'''. Must be unique. Identifies the distribution name.
; <code>utm_campaign</code>: '''The campaign name'''. Must be <code>distribution</code>.
; <code>utm_source</code>: Original referrer. Must be <code>mozilla</code> for both downloadable distributions and campaign tracking.
; <code>utm_medium</code>: Campaign medium. E.g., <code>email</code>. Not used by Firefox.
; <code>utm_term</code>: Search terms. E.g., <code>web+browser</code>. Not used by Firefox.

== Distribution bundles ==

Firefox for Android 46.0 introduced support for distribution bundles based on the '''MCC''' (mobile country code, [https://en.wikipedia.org/wiki/Mobile_country_code]) and '''MNC''' (mobile network code) codes of the inserted SIM card. Instead of the default distribution directory Firefox will search a distribution in the following sub directories first:
* (distribution directory)/''<MCC>''/''<MNC>'' - For bundled distributions for specific network providers
* (distribution directory)/''<MCC>'' - For bundled distributions for specific countries
* (distribution directory)/''default'' - For bundled distributions with no matching MCC/MNC

=== Example distribution bundle ===
distribution
├── 208 // 208 = Country code of France
│   └── bookmarks.json // Bookmarks just for users with a SIM card of a French operator
├── 262 // 262 = Country code of Germany
│   └── 01 // 01 = Network code of "Deutsche Telekom"
│   ├── bookmarks.json // Bookmarks..
│   └── preferences.json // ... and preferences just for users of a SIM card of "Deutsche Telekom"
└── default // Default folder
└── preferences.json // Preferences for all users with different SIM cards.

== Partner Content Providers ==

Android system images can ship with two content providers to customize installed browsers:
* content://com.android.partnerbookmarks - For partner bookmarks
* content://com.android.partnerbrowsercustomizations - For customizations (Details see below)

Firefox for Android supports reading data from both of those content providers (Starting with Firefox for Android 50.0) if this has been enabled by a distribution. If the following preferences are not written by a distribution then Firefox for Android will ignore the data from the partner content providers.

''/distribution/preferences.json:''
<pre>
[..]
"AndroidPreferences": {
"distribution.read_partner_bookmarks_provider": true,
"distribution.read_partner_customizations_provider": true
}
[..]
</pre>

=== Bookmarks Content Provider ===

Firefox for Android (>= 50.0) supports reading bookmarks and folders from the content provider. Reading icons from the content provider is currently not supported (See {{bug|1286203}}). Editing and deleting bookmarks/folders is not supported yet but planned.

An example implementation of the content provider can be found in the official Android source tree:
* https://android.googlesource.com/platform/packages/providers/PartnerBookmarksProvider/+/master/src/com/android/providers/partnerbookmarks/PartnerBookmarksProvider.java

=== Customizations Content Provider ===

Firefox for Android (>= 50.0) only supports reading the 'homepage' from the content provider. All other values are ignored.

content://com.android.partnerbrowsercustomizations

{| class="wikitable"
|-
! Path !! Column !! Supported
|-
| /homepage || homepage || Yes
|-
| /disableincognitomode || disableincognitomode || No
|-
| /disablebookmarksediting || disablebookmarksediting || No
|}

=== Testing ===

There's a test app with sample data available on GitHub:
* https://github.com/pocmo/BrowserPartner

The test app uses slightly different content provider authorities to allow being installed on devices that already ship with partner content providers:

* com.android.partnerbookmarks.'''''test'''''
* com.android.partnerbrowsercustomizations.'''''test'''''

A custom Firefox build is required to read from the test content providers.