Bug 1277407 - Add docs about using adjust sandbox & updating outdated info. r=sebastian, a=lizzard
authorMichael Comella <michael.l.comella@gmail.com>
Fri, 03 Jun 2016 17:00:38 -0700
changeset 339629 2ce49ca619922a2f3b5a58788d5f5c64a58eda28
parent 339628 3e9799b06fe41e72cd7a8d8003e45cf1bf78daa8
child 339630 e2171321a10a8d63c1b55826dabc7119c58d873d
push id6249
push userjlund@mozilla.com
push dateMon, 01 Aug 2016 13:59:36 +0000
treeherdermozilla-beta@bad9d4f5bf7e [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerssebastian, lizzard
bugs1277407
milestone49.0a2
Bug 1277407 - Add docs about using adjust sandbox & updating outdated info. r=sebastian, a=lizzard MozReview-Commit-ID: DW4ZflT8FrZ
mobile/android/docs/adjust.rst
--- a/mobile/android/docs/adjust.rst
+++ b/mobile/android/docs/adjust.rst
@@ -118,27 +118,46 @@ likely to uniquely fingerprint the devic
 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.
+Add the following to your mozconfig to compile with the Adjust SDK::
+
+ export MOZ_INSTALL_TRACKING=1
+ export MOZ_NATIVE_DEVICES=1
+ export RELEASE_BUILD=1
+ ac_add_options --with-adjust-sdk-keyfile="$topsrcdir/mobile/android/base/adjust-sdk-sandbox.token"
+
+``MOZ_NATIVE_DEVICES`` && ``RELEASE_BUILD`` 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_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.
+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``. 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