diff options
Diffstat (limited to 'mobile/android/docs/adjust.rst')
| -rw-r--r-- | mobile/android/docs/adjust.rst | 179 |
1 files changed, 0 insertions, 179 deletions
diff --git a/mobile/android/docs/adjust.rst b/mobile/android/docs/adjust.rst deleted file mode 100644 index 16cb85b2b..000000000 --- a/mobile/android/docs/adjust.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. -*- 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 |