Bug 1277407 - Add docs about using adjust sandbox & updating outdated info. r=sebastian draft
authorMichael Comella <michael.l.comella@gmail.com>
Fri, 03 Jun 2016 17:00:38 -0700
changeset 375342 1a474e3506c180e6c7403a377594203a96b41675
parent 375341 6ee6cf869624b2274338d76b63072d13cc3c8432
child 375343 96930d595ebc22c06dadea1d28782ec6a2c023c2
push id20245
push usermichael.l.comella@gmail.com
push dateSat, 04 Jun 2016 00:01:04 +0000
reviewerssebastian
bugs1277407
milestone49.0a1
Bug 1277407 - Add docs about using adjust sandbox & updating outdated info. r=sebastian 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