Bug 1277407 - Add docs about using adjust sandbox & updating outdated info. r=sebastian
MozReview-Commit-ID: DW4ZflT8FrZ
--- 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