Bug 1159277 - Document Adjust data collection in Firefox for Android. r=mfinkle, r=bsmedberg, a=sledru
authorNick Alexander <nalexander@mozilla.com>
Fri, 01 May 2015 14:20:30 -0700
changeset 265849 7f2f302b43c8bb419cda4cd2d87b156c226ea11d
parent 265848 c7644820e1680e61cc92a4adef28ede87c0b0eed
child 265850 a28c77cdf7bccbecf8ba2b7188841101dabdb74f
push id4718
push userraliiev@mozilla.com
push dateMon, 11 May 2015 18:39:53 +0000
treeherdermozilla-beta@c20c4ef55f08 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmfinkle, bsmedberg, sledru
bugs1159277
milestone39.0a2
Bug 1159277 - Document Adjust data collection in Firefox for Android. r=mfinkle, r=bsmedberg, a=sledru
mobile/android/base/adjust/adjust.rst
mobile/android/base/distribution/ReferrerReceiver.java
mobile/android/base/docs/adjust.rst
mobile/android/base/docs/index.rst
deleted file mode 100644
--- a/mobile/android/base/adjust/adjust.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-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.
-
-An alternative approach would be to build three jars -- one interface jar and
-two implementation jars -- and include one of the implementation jars at
-build-time.  The implementation jars could either define a common symbol, or the
-appropriate symbol could be determined at build-time.  That's a rather heavier
-approach than the one chosen.  If the helper class were to grow to multiple
-classes, with a non-trivial exposed API, this approach could be better.  It
-would also be easier to integrate into the parallel Gradle build system.
--- a/mobile/android/base/distribution/ReferrerReceiver.java
+++ b/mobile/android/base/distribution/ReferrerReceiver.java
@@ -25,17 +25,23 @@ public class ReferrerReceiver extends Br
 
     private static final String ACTION_INSTALL_REFERRER = "com.android.vending.INSTALL_REFERRER";
 
     // Sent when we're done.
     @RobocopTarget
     public static final String ACTION_REFERRER_RECEIVED = "org.mozilla.fennec.REFERRER_RECEIVED";
 
     /**
-     * If the install intent has this source, we'll track the campaign ID.
+     * If the install intent has this source, it is a Mozilla specific or over
+     * the air distribution referral.  We'll track the campaign ID using
+     * Mozilla's metrics systems.
+     *
+     * If the install intent has a source different than this one, it is a
+     * referral from an advertising network.  We may track these campaigns using
+     * third-party tracking and metrics systems.
      */
     private static final String MOZILLA_UTM_SOURCE = "mozilla";
 
     /**
      * If the install intent has this campaign, we'll load the specified distribution.
      */
     private static final String DISTRIBUTION_UTM_CAMPAIGN = "distribution";
 
new file mode 100644
--- /dev/null
+++ b/mobile/android/base/docs/adjust.rst
@@ -0,0 +1,161 @@
+.. -*- 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
+==================================================
+
+The Adjust SDK feature is controlled by the build flag ``MOZ_INSTALL_TRACKING``.  No trace of the
+Adjust SDK should be present in Fennec if this 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_INSTALL_TRACKING_ADJUST_SDK_APP_TOKEN``.  Nota bene: if ``MOZ_INSTALL_TRACKING`` is defined
+but the App-specific token is not specified, Fennec will submit data to a special Adjust sandbox.
+This makes it possible to test the Adjust flow without submitting false data to the install tracking
+backend.
+
+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
--- a/mobile/android/base/docs/index.rst
+++ b/mobile/android/base/docs/index.rst
@@ -2,9 +2,10 @@
 Firefox for Android
 ===================
 
 .. toctree::
    :maxdepth: 1
 
    localeswitching
    uitelemetry
+   adjust
    gradle