Add m-esr52 at 52.6.0

1 files changed, 179 insertions, 0 deletions

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