summaryrefslogtreecommitdiffstats
path: root/mobile/android/docs
diff options
context:
space:
mode:
Diffstat (limited to 'mobile/android/docs')
-rw-r--r--mobile/android/docs/Makefile177
-rw-r--r--mobile/android/docs/adjust.rst179
-rw-r--r--mobile/android/docs/bouncer.rst38
-rw-r--r--mobile/android/docs/conf.py258
-rw-r--r--mobile/android/docs/defaultdomains.rst90
-rw-r--r--mobile/android/docs/index.rst26
-rw-r--r--mobile/android/docs/localeswitching.rst97
-rw-r--r--mobile/android/docs/make.bat242
-rw-r--r--mobile/android/docs/shutdown.rst77
-rw-r--r--mobile/android/docs/uitelemetry.rst271
10 files changed, 1455 insertions, 0 deletions
diff --git a/mobile/android/docs/Makefile b/mobile/android/docs/Makefile
new file mode 100644
index 000000000..c5ddb9080
--- /dev/null
+++ b/mobile/android/docs/Makefile
@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FirefoxforAndroid.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FirefoxforAndroid.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/FirefoxforAndroid"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FirefoxforAndroid"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/mobile/android/docs/adjust.rst b/mobile/android/docs/adjust.rst
new file mode 100644
index 000000000..16cb85b2b
--- /dev/null
+++ b/mobile/android/docs/adjust.rst
@@ -0,0 +1,179 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+======================================
+ Install tracking with the Adjust SDK
+======================================
+
+Fennec (Firefox for Android) tracks certain types of installs using a third party install tracking
+framework called Adjust. The intention is to determine the origin of Fennec installs by answering
+the question, "Did this user on this device install Fennec in response to a specific advertising
+campaign performed by Mozilla?"
+
+Mozilla is using a third party framework in order to answer this question for the Firefox for
+Android 38.0.5 release. We hope to remove the framework from Fennec in the future.
+
+The framework consists of a software development kit (SDK) built into Fennec and a
+data-collecting Internet service backend run by the German company `adjust GmbH`_. The Adjust SDK
+is open source and MIT licensed: see the `github repository`_. Fennec ships a copy of the SDK
+(currently not modified from upstream) in ``mobile/android/thirdparty/com/adjust/sdk``. The SDK is
+documented at https://docs.adjust.com.
+
+Data collection
+~~~~~~~~~~~~~~~
+
+When is data collected and sent to the Adjust backend?
+======================================================
+
+Data is never collected (or sent to the Adjust backend) unless
+
+* the Fennec binary is an official Mozilla binary [#official]_; and
+* the release channel is Release or Beta [#channel]_.
+
+If both of the above conditions are true, then data is collected and sent to the Adjust backend in
+the following two circumstances: first, when
+
+* Fennec is started on the device [#started]_.
+
+Second, when
+
+* the Fennec binary was installed from the Google Play Store; and
+* the Google Play Store sends the installed Fennec binary an `INSTALL_REFERRER Intent`_, and the
+ received Intent includes Google Play Store campaign tracking information. This happens when thea
+ Google Play Store install is in response to a campaign-specific Google Play Store link. For
+ details, see the developer documentation at
+ https://developers.google.com/analytics/devguides/collection/android/v4/campaigns.
+
+In these two limited circumstances, data is collected and sent to the Adjust backend.
+
+Where does data sent to the Adjust backend go?
+==============================================
+
+The Adjust SDK is hard-coded to send data to the endpoint https://app.adjust.com. The endpoint is
+defined by ``com.adjust.sdk.Constants.BASE_URL`` at
+https://hg.mozilla.org/mozilla-central/file/f76f02793f7a/mobile/android/thirdparty/com/adjust/sdk/Constants.java#l27.
+
+The Adjust backend then sends a limited subset of the collected data -- limited but sufficient to
+uniquely identify the submitting device -- to a set of advertising network providers that Mozilla
+elects to share the collected data with. Those advertising networks then confirm or deny that the
+identifying information corresponds to a specific advertising campaign performed by Mozilla.
+
+What data is collected and sent to the Adjust backend?
+======================================================
+
+The Adjust SDK collects and sends two messages to the Adjust backend. The messages have the
+following parameters::
+
+ V/Adjust ( 6508): Parameters:
+ V/Adjust ( 6508): screen_format normal
+ V/Adjust ( 6508): device_manufacturer samsung
+ V/Adjust ( 6508): session_count 1
+ V/Adjust ( 6508): device_type phone
+ V/Adjust ( 6508): screen_size normal
+ V/Adjust ( 6508): package_name org.mozilla.firefox
+ V/Adjust ( 6508): app_version 39.0a1
+ V/Adjust ( 6508): android_uuid <guid>
+ V/Adjust ( 6508): display_width 720
+ V/Adjust ( 6508): country GB
+ V/Adjust ( 6508): os_version 18
+ V/Adjust ( 6508): needs_attribution_data 0
+ V/Adjust ( 6508): environment sandbox
+ V/Adjust ( 6508): device_name Galaxy Nexus
+ V/Adjust ( 6508): os_name android
+ V/Adjust ( 6508): tracking_enabled 1
+ V/Adjust ( 6508): created_at 2015-03-24T17:53:38.452Z-0400
+ V/Adjust ( 6508): app_token <private>
+ V/Adjust ( 6508): screen_density high
+ V/Adjust ( 6508): language en
+ V/Adjust ( 6508): display_height 1184
+ V/Adjust ( 6508): gps_adid <guid>
+
+ V/Adjust ( 6508): Parameters:
+ V/Adjust ( 6508): needs_attribution_data 0
+ V/Adjust ( 6508): app_token <private>
+ V/Adjust ( 6508): environment production
+ V/Adjust ( 6508): android_uuid <guid>
+ V/Adjust ( 6508): tracking_enabled 1
+ V/Adjust ( 6508): gps_adid <guid>
+
+The available parameters (including ones not exposed to Mozilla) are documented at
+https://partners.adjust.com/placeholders/.
+
+Notes on what data is collected
+-------------------------------
+
+The *android_uuid* uniquely identifies the device.
+
+The *gps_adid* is a Google Advertising ID. It is capable of uniquely identifying a device to any
+advertiser, across all applications. If a Google Advertising ID is not available, Adjust may fall
+back to an Android ID, or, as a last resort, the device's WiFi MAC address.
+
+The *tracking_enabled* flag is only used to allow or disallow contextual advertising to be sent to a
+user. It can be, and is, ignored for general install tracking of the type Mozilla is using the
+Adjust SDK for. (This flag might be used by consumers using the Adjust SDK to provide in-App
+advertising.)
+
+It is not clear how much entropy their is in the set of per-device parameters that do not
+*explicitly* uniquely identify the device. That is, it is not known if the device parameters are
+likely to uniquely fingerprint the device, in the way that user agent capabilities are likely to
+uniquely fingerprint the user.
+
+Technical notes
+~~~~~~~~~~~~~~~
+
+Build flags controlling the Adjust SDK integration
+==================================================
+
+Add the following to your mozconfig to compile with the Adjust SDK::
+
+ export MOZ_INSTALL_TRACKING=1
+ export MOZ_NATIVE_DEVICES=1
+ export RELEASE_OR_BETA=1
+ ac_add_options --with-adjust-sdk-keyfile="$topsrcdir/mobile/android/base/adjust-sdk-sandbox.token"
+
+``MOZ_NATIVE_DEVICES`` && ``RELEASE_OR_BETA`` are required for an unknown
+reason. If you build without them, the ``StubAdjustHelper`` will be
+returned.
+
+No trace of the Adjust SDK should be present in Fennec if
+``MOZ_INSTALL_TRACKING`` is not defined.
+
+Access to the Adjust backend is controlled by a private App-specific
+token. Fennec's token is managed by Release Engineering and should not
+be exposed if at all possible; for example, it should *not* leak to build
+logs. The value of the token is read from the file specified using the
+``configure`` flag ``--with-adjust-sdk-keyfile=KEYFILE`` and stored in
+the build variable ``MOZ_ADJUST_SDK_KEY``. The mozconfig specified above
+defaults to submitting data to a special Adjust sandbox allowing a
+developer to test Adjust without submitting false data to our backend.
+
+We throw an assertion if ``MOZ_INSTALL_TRACKING`` is specified but
+``--with-adjust-sdk-keyfile`` is not to ensure our builders have a proper
+adjust token for release and beta builds. It's great to catch some
+errors at compile-time rather than in release. That being said, ideally
+we'd specify a default ``--with-adjust-sdk-keyfile`` for developer builds
+but I don't know how to do that.
+
+Technical notes on the Adjust SDK integration
+=============================================
+
+The *Adjust install tracking SDK* is a pure-Java library that is conditionally compiled into Fennec.
+It's not trivial to integrate such conditional feature libraries into Fennec without pre-processing.
+To minimize such pre-processing, we define a trivial ``AdjustHelperInterface`` and define two
+implementations: the real ``AdjustHelper``, which requires the Adjust SDK, and a no-op
+``StubAdjustHelper``, which has no additional requirements. We use the existing pre-processed
+``AppConstants.java.in`` to switch, at build-time, between the two implementations.
+
+Notes and links
+===============
+
+.. _adjust GmbH: http://www.adjust.com
+.. _github repository: https://github.com/adjust/android_sdk
+.. [#official] Data is not sent for builds not produced by Mozilla: this would include
+ redistributors such as the Palemoon project.
+.. [#channel] Data is not sent for Aurora, Nightly, or custom builds.
+.. [#started] *Started* means more than just when the user taps the Fennec icon or otherwise causes
+ the Fennec user interface to appear directly. It includes, for example, when a Fennec service
+ (like the Update Service, or Background Sync), starts and Fennec was not previously running on the
+ device. See http://developer.android.com/reference/android/app/Application.html#onCreate%28%29
+ for details.
+.. _INSTALL_REFERRER Intent: https://developer.android.com/reference/com/google/android/gms/tagmanager/InstallReferrerReceiver.html
diff --git a/mobile/android/docs/bouncer.rst b/mobile/android/docs/bouncer.rst
new file mode 100644
index 000000000..6ba4a5f30
--- /dev/null
+++ b/mobile/android/docs/bouncer.rst
@@ -0,0 +1,38 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+=========================================
+ The Firefox for Android install bouncer
+=========================================
+
+`Bug 1234629 <https://bugzilla.mozilla.org/show_bug.cgi?id=1234629>`_ and `Bug 1163082
+<https://bugzilla.mozilla.org/show_bug.cgi?id=1163082>`_ combine to allow building a very small
+Fennec-like "bouncer" APK that redirects (bounces) a potential Fennec user to the marketplace of
+their choice -- usually the Google Play Store -- to install the real Firefox for Android application
+APK.
+
+The real APK should install seamlessly over top of the bouncer APK. Care is taken to keep the
+bouncer and application APK <permission> manifest definitions identical, and to have the bouncer APK
+<activity> manifest definitions look similar to the application APK <activity> manifest definitions.
+
+In addition, the bouncer APK can carry a Fennec distribution, which it copies onto the device before
+redirecting to the marketplace. The application APK recognizes the installed distribution and
+customizes itself accordingly on first run.
+
+The motivation is to allow partners to pre-install the very small bouncer APK on shipping devices
+and to have a smooth path to upgrade to the full application APK, with a partner-specific
+distribution in place.
+
+Technical details
+=================
+
+To build the bouncer APK, define ``MOZ_ANDROID_PACKAGE_INSTALL_BOUNCER``. To pack a distribution
+into the bouncer APK (and *not* into the application APK), add a line like::
+
+ ac_add_options --with-android-distribution-directory=/path/to/fennec-distribution-sample
+
+to your ``mozconfig`` file. See the `general distribution documentation on the wiki
+<https://wiki.mozilla.org/Mobile/Distribution_Files>`_ for more information.
+
+The ``distribution`` directory should end up in the ``assets/distribution`` directory of the bouncer
+APK. It will be copied into ``/data/data/$ANDROID_PACKAGE_NAME/distribution`` when the bouncer
+executes.
diff --git a/mobile/android/docs/conf.py b/mobile/android/docs/conf.py
new file mode 100644
index 000000000..8eda58960
--- /dev/null
+++ b/mobile/android/docs/conf.py
@@ -0,0 +1,258 @@
+# -*- coding: utf-8 -*-
+#
+# Firefox for Android documentation build configuration file, created by
+# sphinx-quickstart on Fri Dec 4 22:51:57 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Firefox for Android'
+copyright = u'2015, mobile team'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'FirefoxforAndroiddoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'FirefoxforAndroid.tex', u'Firefox for Android Documentation',
+ u'mobile team', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'firefoxforandroid', u'Firefox for Android Documentation',
+ [u'mobile team'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'FirefoxforAndroid', u'Firefox for Android Documentation',
+ u'mobile team', 'FirefoxforAndroid', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/mobile/android/docs/defaultdomains.rst b/mobile/android/docs/defaultdomains.rst
new file mode 100644
index 000000000..470c2c8ec
--- /dev/null
+++ b/mobile/android/docs/defaultdomains.rst
@@ -0,0 +1,90 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+==========================
+ Shipping Default Domains
+==========================
+
+Firefox for Mobile (Android and iOS) ships sets of default content in order to improve the
+first-run experience. There are two primary places where default sets of domains are used: URLBar
+domain auto-completion, and Top Sites suggested thumbnails.
+
+The source of these domains is typically the Alexa top sites lists, global and by-country. Before
+shipping the sets of domains, the lists are sanitized.
+
+Domain Auto-completion
+======================
+
+As you type in the URLBar, Firefox will scan your history and auto-complete previously visited
+domains that match what you have entered. This can make navigating to web sites faster because it
+can avoid significant amounts of typing. During your first few uses, Firefox does not have any
+history and you are forced to type full URLs. Shipping a set of top domains provides a fallback.
+
+The top domains list can be localized, but Firefox will fallback to using en-US as the default for all
+locales that do not provide a specific set. The list can have several hundred domains, but due to
+size concerns, is usually capped to five hundred or less.
+
+Sanitizing Methods
+------------------
+
+After getting a source list, e.g. Alexa top global sites, we apply some simple guidelines to the
+list of domains:
+
+
+* Remove any sites in the Alexa adult site list.
+* Remove any locale-specific domain duplicates. We assume primary URLs (.com) will redirect to the
+ correct locale (.co.jp) at run-time.
+* Remove any explicit adult content* domains.
+* Remove any sites that use explicit or adult advertising*.
+* Remove any URL shorteners and redirecters.
+* Remove any content/CDN domains. Some sites use separate domains to store images and other static content.
+* Remove any sites primarily used for advertising or management of advertising.
+* Remove any sites that fail to load in mobile browsers.
+* Remove any time/date specific sites that may have appeared on the list due to seasonal spikes.
+
+Suggested Sites
+===============
+
+Suggested sites are default thumbnails, displayed on the Top Sites home panel. A suggested site
+consists of a title, thumbnail image, background color and URL. Multiple images are usually
+required to handle the variety of device DPIs.
+
+Suggested sites can be localized, but Firefox will fallback to using en-US as the default for all
+locales that do not provide a specific set. The list is usually small, with perhaps fewer than ten
+sites.
+
+Sanitizing Methods
+------------------
+
+After getting a source list, e.g. Alexa top global sites, we apply some simple guidelines to the
+list of domains:
+
+* Remove pure search engines. We handle search engines differently and don't consider them to be
+ suggested sites.
+* Remove any locale-specific domain duplicates. We assume primary URLs (.com) will redirect to the
+ correct locale (.co.jp) at run-time.
+* Remove any explicit adult content domains.
+* Remove any sites that use explicit or adult advertising.
+* Remove any URL shorteners and redirecters.
+* Remove any content/CDN domains. Some sites use separate domains to store images and other static
+ content.
+
+Guidelines for Adult Content
+============================
+
+Generally the Adult category includes sites whose dominant theme is either:
+
+* To appeal to the prurient interest in sex without any serious literary, artistic, political, or
+ scientific value
+* The depiction or description of nudity, including sexual or excretory activities or organs in a
+ lascivious way
+* The depiction or description of sexually explicit conduct in a lascivious way (e.g. for
+ entertainment purposes)
+
+For a more complete definition and guidelines of adult content, use the full DMOZ guidelines at
+http://www.dmoz.org/docs/en/guidelines/adult/general.html.
+
+Updating Lists
+==============
+
+After approximately every two releases, Product (with Legal) will review current lists and
+sanitizing methods, and update the lists accordingly.
diff --git a/mobile/android/docs/index.rst b/mobile/android/docs/index.rst
new file mode 100644
index 000000000..8295f2954
--- /dev/null
+++ b/mobile/android/docs/index.rst
@@ -0,0 +1,26 @@
+.. Firefox for Android documentation master file, created by
+ sphinx-quickstart on Fri Dec 4 22:51:57 2015.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Firefox for Android
+===================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ localeswitching
+ uitelemetry
+ adjust
+ defaultdomains
+ bouncer
+ shutdown
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/mobile/android/docs/localeswitching.rst b/mobile/android/docs/localeswitching.rst
new file mode 100644
index 000000000..8fcb41976
--- /dev/null
+++ b/mobile/android/docs/localeswitching.rst
@@ -0,0 +1,97 @@
+.. -*- Mode: rst; fill-column: 80; -*-
+
+====================================
+ Runtime locale switching in Fennec
+====================================
+
+`Bug 917480 <https://bugzilla.mozilla.org/show_bug.cgi?id=917480>`_ built on `Bug 936756 <https://bugzilla.mozilla.org/show_bug.cgi?id=936756>`_ to allow users to switch between supported locales at runtime, within Fennec, without altering the system locale.
+
+This document aims to describe the overall architecture of the solution, along with guidelines for Fennec developers.
+
+Overview
+========
+
+There are two places that locales are relevant to an Android application: the Java ``Locale`` object and the Android configuration itself.
+
+Locale switching involves manipulating these values (to affect future UI), persisting them for future activities, and selectively redisplaying existing UI elements to give the appearance of responsive switching.
+
+The user's choice of locale is stored in a per-app pref, ``"locale"``. If missing, the system default locale is used. If set, it should be a locale code like ``"es"`` or ``"en-US"``.
+
+``BrowserLocaleManager`` takes care of updating the active locale when asked to do so. It also manages persistence and retrieval of the locale preference.
+
+The question, then, is when to do so.
+
+Locale events
+=============
+
+One might imagine that we need only set the locale when our Application is instantiated, and when a new locale is set. Alas, that's not the case: whenever there's a configuration change (*e.g.*, screen rotation), when a new activity is started, and at other apparently random times, Android will supply our activities with a configuration that's been reset to the system locale.
+
+For this reason, each starting activity must ask ``BrowserLocaleManager`` to fix its locale.
+
+Ideally, we also need to perform some amount of work when our configuration changes, when our activity is resumed, and perhaps when a result is returned from another activity, if that activity can change the app locale (as is the case for any activity that calls out to ``GeckoPreferences`` -- see ``BrowserApp#onActivityResult``).
+
+``GeckoApp`` itself does some additional work, because it has particular performance constraints, and also is the typical root of the preferences activity.
+
+Here's an example of the work that a typical activity should do::
+
+ // This is cribbed from o.m.g.sync.setup.activities.LocaleAware.
+ public static void initializeLocale(Context context) {
+ final LocaleManager localeManager = BrowserLocaleManager.getInstance();
+ if (Build.VERSION.SDK_INT < Build.VERSION_CODES.GINGERBREAD) {
+ localeManager.getAndApplyPersistedLocale(context);
+ } else {
+ final StrictMode.ThreadPolicy savedPolicy = StrictMode.allowThreadDiskReads();
+ StrictMode.allowThreadDiskWrites();
+ try {
+ localeManager.getAndApplyPersistedLocale(context);
+ } finally {
+ StrictMode.setThreadPolicy(savedPolicy);
+ }
+ }
+ }
+
+ @Override
+ public void onConfigurationChanged(Configuration newConfig) {
+ final LocaleManager localeManager = BrowserLocaleManager.getInstance();
+ final Locale changed = localeManager.onSystemConfigurationChanged(this, getResources(), newConfig, mLastLocale);
+ if (changed != null) {
+ // Redisplay to match the locale.
+ onLocaleChanged(BrowserLocaleManager.getLanguageTag(changed));
+ }
+ }
+
+ @Override
+ public void onCreate(Bundle icicle) {
+ // Note that we don't do this in onResume. We should,
+ // but it's an edge case that we feel free to ignore.
+ // We also don't have a hook in this example for when
+ // the user picks a new locale.
+ initializeLocale(this);
+
+ super.onCreate(icicle);
+ }
+
+``GeckoApplication`` itself handles correcting locales when the configuration changes; your activity shouldn't need to do this itself. See ``GeckoApplication``'s and ``GeckoApp``'s ``onConfigurationChanged`` methods.
+
+System locale changes
+=====================
+
+Fennec can be in one of two states.
+
+If the user has not explicitly chosen a Fennec-specific locale, we say
+we are "mirroring" the system locale.
+
+When we are not mirroring, system locale changes do not impact Fennec
+and are essentially ignored; the user's locale selection is the only
+thing we care about, and we actively correct incoming configuration
+changes to reflect the user's chosen locale.
+
+By contrast, when we are mirroring, system locale changes cause Fennec
+to reflect the new system locale, as if the user picked the new locale.
+
+When the system locale changes when we're mirroring, your activity will receive an ``onConfigurationChanged`` call. Simply pass this on to ``BrowserLocaleManager``, and then handle the response appropriately.
+
+Further reference
+=================
+
+``GeckoPreferences``, ``GeckoApp``, and ``BrowserApp`` are excellent resources for figuring out what you should do.
diff --git a/mobile/android/docs/make.bat b/mobile/android/docs/make.bat
new file mode 100644
index 000000000..d916a4c8f
--- /dev/null
+++ b/mobile/android/docs/make.bat
@@ -0,0 +1,242 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. xml to make Docutils-native XML files
+ echo. pseudoxml to make pseudoxml-XML files for display purposes
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\FirefoxforAndroid.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\FirefoxforAndroid.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdf" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdfja" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf-ja
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+if "%1" == "xml" (
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.
+ goto end
+)
+
+if "%1" == "pseudoxml" (
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+ goto end
+)
+
+:end
diff --git a/mobile/android/docs/shutdown.rst b/mobile/android/docs/shutdown.rst
new file mode 100644
index 000000000..9ec0655f9
--- /dev/null
+++ b/mobile/android/docs/shutdown.rst
@@ -0,0 +1,77 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+===================================
+ Shutting down Firefox for Android
+===================================
+
+Background
+==========
+
+Normally, apps on Android don't need to provide any support for explicit quitting, instead they are
+just sent into the background where they eventually get killed by the OS's low-memory killer.
+
+Nevertheless, Firefox on Android allows explicit quitting to support the use case of users wanting
+to clear part or all of their private data after finishing a browsing session. When this option to
+"Clear private data on exit" is activated from the settings, a "Quit" button is provided in the menu.
+
+Because Firefox on Android uses a native UI (written in Java), which also holds some of the user's
+browsing data, this creates some additional complications when compared to quitting on desktop.
+
+Technical details
+=================
+
+When the "Quit" button is used, the UI sends a ``Browser:Quit`` notification to Gecko's ``BrowserApp``,
+which initiates the normal Gecko shutdown procedure. At the same time however, the native UI needs to
+shutdown as well, so as to
+
+1) provide an immediate visual feedback to the user that Firefox is indeed quitting
+
+2) avoid a state where the UI is still running "normally" while the rendering engine is already
+ shutting down, which could lead to loosing incoming external tabs if they were to arrive within
+ that period.
+
+Therefore, shutdown of the native UI was originally started simultaneously with notifying Gecko.
+Because the clearing of private data during shutdown is handled by Gecko's ``Sanitizer``, while some
+private data, e.g. the browsing history, is held in a database by the native UI, this means that
+Gecko needs to message the native UI during shutdown if the user wants the browsing history to be
+cleared on quitting.
+Shutting down the UI simultaneously with Gecko therefore introduced a race condition where the data
+clearing could fail because the native UI thread responsible for receiving Gecko's sanitization
+messages had already exited by the time Gecko's ``Sanitizer`` was attempting to e.g. clear the
+user's browsing history (for further reading, compare `bug 1266594
+<https://bugzilla.mozilla.org/show_bug.cgi?id=1266594>`_).
+
+To fix this issue, the native UI (in ``GeckoApp``) now waits for the ``Sanitizer`` to run and
+message all necessary sanitization handlers and only starts its shutdown after receiving a
+``Sanitize:Finished`` message with a ``shutdown: true`` parameter set. While this introduces a
+certain delay in closing the UI, it is still faster than having to wait for Gecko to exit completely
+before starting to close the UI.
+
+Currently, quitting Firefox therefore proceeds roughly as follows:
+
+1) The user presses the "Quit" button in the main menu, which sends a ``Browser:Quit`` notification
+ to ``BrowserApp``. This notification also contains additional parameters indicating which types
+ of private user data - if any - to clear during shutdown.
+
+2) ``BrowserApp.quit`` runs, which initiates Gecko shutdown by sending out a
+ ``quit-application-requested`` notification.
+
+3) If nobody cancelled shutdown in response to the ``quit-application-requested`` notification,
+ quitting proceeds and the ``SessionStore`` enters shutdown mode (``STATE_QUITTING``), which
+ basically means that no new (asynchronous) writes are started to prevent any interference with
+ the final flushing of data.
+
+4) ``BrowserApp`` calls the ``Sanitizer`` to clear up any private user data that might need cleaning.
+ After the ``Sanitizer`` has invoked all required sanitization handlers (including any on the
+ native Java UI side, e.g. for the browsing history) and finished running, it sends a
+ ``Sanitize:Finished`` message back to the native UI.
+
+5) On receiving the ``Sanitize:Finished`` message, ``GeckoApp`` starts the shutdown of the native UI
+ as well by calling ``doShutdown()``.
+
+6) After sending the ``Sanitize:Finished`` message, Gecko's ``Sanitizer`` runs the callback provided
+ by ``BrowserApp.quit``, which is ``appStartup.quit(Ci.nsIAppStartup.eForceQuit)``, thereby
+ starting the actual and final shutting down of Gecko.
+
+7) On receiving the final ``quit-application`` notification, the ``SessionStore`` synchronously
+ writes its current state to disk.
diff --git a/mobile/android/docs/uitelemetry.rst b/mobile/android/docs/uitelemetry.rst
new file mode 100644
index 000000000..d592acbb6
--- /dev/null
+++ b/mobile/android/docs/uitelemetry.rst
@@ -0,0 +1,271 @@
+.. -*- Mode: rst; fill-column: 80; -*-
+
+==============
+ UI Telemetry
+==============
+
+Fennec records UI events using a telemetry framework called UITelemetry.
+
+Some links:
+
+- `Project page <https://wiki.mozilla.org/Mobile/Projects/Telemetry_probes_for_Fennec_UI_elements>`_
+- `Wiki page <https://wiki.mozilla.org/Mobile/Fennec/Android/UITelemetry>`_
+- `User research notes <https://wiki.mozilla.org/Mobile/User_Experience/Research>`_
+
+Sessions
+========
+
+**Sessions** are essentially scopes. They are meant to provide context to
+events; this allows events to be simpler and more reusable. Sessions are
+usually bound to some component of the UI, some user action with a duration, or
+some transient state.
+
+For example, a session might be begun when a user begins interacting with a
+menu, and stopped when the interaction ends. Or a session might encapsulate
+period of no network connectivity, the first five seconds after the browser
+launched, the time spent with an active download, or a guest mode session.
+
+Sessions implicitly record the duration of the interaction.
+
+A simple use-case for sessions is the bookmarks panel in about:home. We start a
+session when the user swipes into the panel, and stop it when they swipe away.
+This bookmarks session does two things: firstly, it gives scope to any generic
+event that may occur within the panel (*e.g.*, loading a URL). Secondly, it
+allows us to figure out how much time users are spending in the bookmarks
+panel.
+
+To start a session, call ``Telemetry.startUISession(String sessionName)``.
+
+``sessionName``
+ The name of the session. Session names should be brief, lowercase, and should describe which UI
+ component the user is interacting with. In certain cases where the UI component is dynamic, they could include an ID, essential to identifying that component. An example of this is dynamic home panels: we use session names of the format ``homepanel:<panel_id>`` to identify home panel sessions.
+
+To stop a session, call ``Telemetry.stopUISession(String sessionName, String reason)``.
+
+``sessionName``
+ The name of the open session
+
+``reason`` (Optional)
+ A descriptive cause for ending the session. It should be brief, lowercase, and generic so it can be reused in different places. Examples reasons are:
+
+ ``switched``
+ The user transitioned to a UI element of equal level.
+
+ ``exit``
+ The user left for an entirely different element.
+
+Events
+======
+
+Events capture key occurrences. They should be brief and simple, and should not contain sensitive or excess information. Context for events should come from the session (scope). An event can be created with four fields (via ``Telemetry.sendUIEvent``): ``action``, ``method``, ``extras``, and ``timestamp``.
+
+``action``
+ The name of the event. Should be brief and lowercase. If needed, you can make use of namespacing with a '``.``' separator. Example event names: ``panel.switch``, ``panel.enable``, ``panel.disable``, ``panel.install``.
+
+``method`` (Optional)
+ Used for user actions that can be performed in many ways. This field specifies the method by which the action was performed. For example, users can add an item to their reading list either by long-tapping the reader icon in the address bar, or from within reader mode. We would use the same event name for both user actions but specify two methods: ``addressbar`` and ``readermode``.
+
+``extras`` (Optional)
+ For extra information that may be useful in understanding the event. Make an effort to keep this brief.
+
+``timestamp`` (Optional)
+ The time at which the event occurred. If not specified, this field defaults to the current value of the realtime clock.
+
+Versioning
+==========
+
+As a we improve on our Telemetry methods, it is foreseeable that our probes will change over time. Different versions of a probe could carry different data or have different interpretations on the server-side. To make it easier for the server to handle these changes, you should add version numbers to your event and session names. An example of a versioned session is ``homepanel.1``; this is version 1 of the ``homepanel`` session. This approach should also be applied to event names, an example being: ``panel.enable.1`` and ``panel.enable.2``.
+
+
+Clock
+=====
+
+Times are relative to either elapsed realtime (an arbitrary monotonically increasing clock that continues to tick when the device is asleep), or elapsed uptime (which doesn't tick when the device is in deep sleep). We default to elapsed realtime.
+
+See the documentation in `the source <http://dxr.mozilla.org/mozilla-central/source/mobile/android/base/Telemetry.java>`_ for more details.
+
+Dictionary
+==========
+
+Events
+------
+``action.1``
+ Generic action, usually for tracking menu and toolbar actions.
+
+``cancel.1``
+ Cancel a state, action, etc.
+
+``cast.1``
+ Start casting a video.
+
+``edit.1``
+ Sent when the user edits a top site.
+
+``launch.1``
+ Launching (opening) an external application.
+ Note: Only used in JavaScript for now.
+
+``loadurl.1``
+ Loading a URL.
+
+``locale.browser.reset.1``
+ When the user chooses "System default" in the browser locale picker.
+
+``locale.browser.selected.1``
+ When the user chooses a locale in the browser locale picker. The selected
+ locale is provided as the extra.
+
+``locale.browser.unselected.1``
+ When the user chose a different locale in the browser locale picker, this
+ event is fired with the previous locale as the extra. If the previous locale
+ could not be determined, "unknown" is provided.
+
+``neterror.1``
+ When the user performs actions on the in-content network error page. This should probably be a ``Session``, but it's difficult to start and stop the session reliably.
+
+``panel.hide.1``
+ Hide a built-in home panel.
+
+``panel.move.1``
+ Move a home panel up or down.
+
+``panel.remove.1``
+ Remove a custom home panel.
+
+``panel.setdefault.1``
+ Set default home panel.
+
+``panel.show.1``
+ Show a hidden built-in home panel.
+
+``pin.1``, ``unpin.1``
+ Sent when the user pinned or unpinned a top site.
+
+``policynotification.success.1:true``
+ Sent when a user has accepted the data notification policy. Can be ``false``
+ instead of ``true`` if an error occurs.
+
+``sanitize.1``
+ Sent when the user chooses to clear private data.
+
+``save.1``, ``unsave.1``
+ Saving or unsaving a resource (reader, bookmark, etc.) for viewing later.
+
+``search.1``
+ Sent when the user performs a search. Currently used in the search activity.
+
+``search.remove.1``
+ Sent when the user removes a search engine.
+
+``search.restore.1``
+ Sent when the user restores the search engine configuration back to the built-in configuration.
+
+``search.setdefault.1``
+ Sent when the user sets a search engine to be the default.
+
+``share.1``
+ Sharing content.
+
+``show.1``
+ Sent when a contextual UI element is shown to the user.
+
+``undo.1``
+ Sent when performing an undo-style action, like undoing a closed tab.
+
+Methods
+-------
+``actionbar``
+ Action triggered from an ActionBar UI.
+
+``back``
+ Action triggered from the back button.
+
+``banner``
+ Action triggered from a banner (such as HomeBanner).
+
+``button``
+ Action triggered from a button.
+ Note: Only used in JavaScript for now.
+
+``content``
+ Action triggered from a content page.
+
+``contextmenu``
+ Action triggered from a contextmenu. Could be from chrome or content.
+
+``dialog``
+ Action triggered from a dialog.
+
+``doorhanger``
+ Action triggered from a doorhanger popup prompt.
+
+``griditem``
+ Action triggered from a griditem, such as those used in Top Sites panel.
+
+``homescreen``
+ Action triggered from a homescreen shortcut icon.
+
+``intent``
+ Action triggered from a system Intent, usually sent from the OS.
+
+``list``
+ Action triggered from an unmanaged list of items, usually provided by the OS.
+
+``listitem``
+ Action triggered from a listitem.
+
+``menu``
+ Action triggered from the main menu.
+
+``notification``
+ Action triggered from a system notification.
+
+``pageaction``
+ Action triggered from a pageaction, displayed in the URL bar.
+
+``service``
+ Action triggered from an automatic system making a decision.
+
+``settings``
+ Action triggered from a content page.
+
+``shareoverlay``
+ Action triggered from a content page.
+
+``suggestion``
+ Action triggered from a suggested result, like those from search engines or default tiles.
+
+``system``
+ Action triggered from an OS level action, like application foreground / background.
+
+``toast``
+ Action triggered from an unobtrusive, temporary notification.
+
+``widget``
+ Action triggered from a widget placed on the homescreen.
+
+Sessions
+--------
+``awesomescreen.1``
+ Awesomescreen (including frecency search) is active.
+
+``firstrun.1``
+ Started the very first time we believe the application has been launched.
+
+``frecency.1``
+ Awesomescreen frecency search is active.
+
+``homepanel.1``
+ Started when a user enters a given home panel.
+ Session name is dynamic, encoded as "homepanel.1:<panel_id>"
+ Built-in home panels have fixed IDs
+
+``reader.1``
+ Reader viewer becomes active in the foreground.
+
+``searchactivity.1``
+ Started when the user launches the search activity (onStart) and stopped
+ when they leave the search activity.
+
+``settings.1``
+ Settings activity is active.
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-05 03:02:42 +0000