Bug 1373174 - Add general documentation for Leanplum. r?liuche draft
authorNevin Chen <cnevinchen@gmail.com>
Thu, 15 Jun 2017 16:57:32 +0800
changeset 599648 e00572bc1e090cd960c58be8c9cc618917383037
parent 599416 7455c74d833a9db4e02be17eda14588c7ef0de76
child 634808 f76751a09f9abc6d41ae1f04f795ec37805801f0
push id65558
push userbmo:cnevinchen@gmail.com
push dateFri, 23 Jun 2017 09:57:35 +0000
reviewersliuche
bugs1373174
milestone56.0a1
Bug 1373174 - Add general documentation for Leanplum. r?liuche MozReview-Commit-ID: 2dz8eR7tnUT
mobile/android/docs/mma.rst
new file mode 100644
--- /dev/null
+++ b/mobile/android/docs/mma.rst
@@ -0,0 +1,145 @@
+.. -*- Mode: rst; fill-column: 100; -*-
+
+======================================
+ MMA Mobile Marketing Automation
+======================================
+
+We want to engage with users more. MMA is the project for this purpose. When a user performs a certain
+UI action, he/she will see a prompt and have a chance to  interact with it. For example, if a user uses
+Firefox 10 times a week, but Firefox is not his default browser, we'll prompt the user the next time
+when he launchers our app, and guide him to set us as default browser.
+
+Mozilla is using a third party framework called "Leanplum" in order to achieve above goal for
+Android 56 release. Leanplum is a San Francisco company, founded in 2012. We put their SDK in
+our codebase and sync upstream when there's a major update. Please find it in ``mobile/android/thirdparty/com/leanplum``.
+The SDK is documented at https://www.leanplum.com/docs/android/
+
+There are three major component in Leanplum SDK.
+1. Events : Triggers when users perform certain actions. An event will normally trigger a prompt message.
+2. Deep Links : Actions that users can perform to interact with the prompt message.
+3. Messages :  Campaigns that we want to engage with users. Messages is a combination of an Event and a Deep Link.
+
+
+Data collection
+~~~~~~~~~~~~~~~
+
+Who will have Leanplum enabled?
+======================================================
+
+* We use Switchboard to filter users to have Leanplum enabled. Currently, for users in the USA
+  and whose locale is set to English, 10% of that users will have Leanplum enabled.
+* If the user has "Health Report" setting enabled.
+* If above two are true, when the app starts, and switchboard configure arrived, Fennec will send the
+  triggers and message interaction history to Leanplum server when available.
+
+
+Where does data sent to the Leaplum backend go?
+==============================================
+
+The Leanplum SDK is hard-coded to send data to the endpoint https://www.leanplum.com.  The endpoint is
+defined by ``com.leanplum.internal.Constants.API_HOST_NAME`` at
+https://searchfox.org/mozilla-central/rev/c49a70b53f67dd5550eec8a08793805f2aca8d42/mobile/android/thirdparty/com/leanplum/internal/Constants.java#32.
+
+The user is identified by Leanplum using a random UUID generated by Fennec when Leanplum is initialized for the first time.
+This unique identifier is only used by Leanplum and can't be tracked back to any Firefox users.
+
+
+What data is collected and sent to the Leanplum backend?
+======================================================
+
+The Leanplum SDK collects and sends two messages to the Leanplum backend.  The messages have the
+following parameters::
+
+// things we are collecting to use specifically for campaigns
+  "action" -> "start"                   // start: Leanplum SDK starts. track: an event is tracked.
+  "event" -> "Launch"                   // Used when an event is triggered. e.g. SaveBookmark.
+  "info" -> ""                          // Used when an event is triggered. Basic context associated with the event.
+  "value" -> 0.0                        // Used when an event is triggered. Value of that event.
+  "messageId" -> 5111602214338560       // Used when an event is triggered. The ID of the message.
+
+// User related information,
+  "userAttributes" -> "{                // A set of key-value pairs used to describe the user.
+    "focus" -> "installed"              // Currently we are only tracking if Focus for Android is installed.
+  }"
+  "deviceId" -> "b13b3c239d01aa7c"      // Set by Fennec, we use random uuid so users are anonymous to Leanplum.
+  "userId" -> "b13b3c239d01aa7c"        // Same as above.
+  "appId" -> "app_6Ao...."              // Leanplum App ID.
+  "clientKey" -> "dev_srwDUNZR...."     // Leanplum client access key.
+
+// basic system data:
+  "systemName" -> "Android OS"          // Fixed String in SDK.
+  "time" -> "1.497595093902E9"          // System time in second.
+  "token" -> "nksZ5pa0R5iegC7wj...."    // from Leanplum backend.
+  "locale" -> "zh_TW"                   // System Locale.
+  "devMode" -> "true"                   // If the SDK is in developer mode.
+  "timezone" -> "Asia/Taipei"           // System Timezone.
+  "versionName" -> "55.0a1"             // Fennec version.
+  "systemVersion" -> "7.1.2"            // System version.
+  "sdkVersion" -> "2.2.2-SNAPSHOT"      // Leanplum SDK version.
+  "deviceModel" -> "Google Pixel"       // System device model.
+  "timezoneOffsetSeconds" -> "28800"    // User timezone offset with PST.
+  "deviceName" -> "Google Pixel"        // System device name.
+
+// Not used:
+  "region" -> "(detect)"                // Not used. We strip play-SERVICES-location so this is will be the default stub value in Leanplum SDK.
+  "city" -> "(detect)"                  // Same as above.
+  "country" -> "(detect)"               // Same as above.
+  "location" -> "(detect)"              // Same as above.
+  "newsfeedMessages" -> " size = 0"     // Not used. New Leanpum Inbox message(Leanplum feature) count.
+  "includeDefaults" -> "false"          // Not used. Always false.
+
+
+Notes on what data is collected
+-------------------------------
+
+User Identifier:
+Since Device ID is a random UUID, Leanplum can't map the device to any know Client ID in Fennec nor Advertising ID.
+
+Events:
+Most of the Leanplum events can be mapped to a single combination of Telemetry event (Event+Method+Extra).
+Some events are not collected in Mozilla Telemetry. This will be addressed separately in each campaign review.
+List of current Events are :
+
+Deep Links:
+Deep links are actions that can point Fennec to open certain pages or load features such as `show bookmark list` or
+`open a SUMO page`. This data is not colloected by Leanplum (To be confirmed)
+
+Messages :
+Messages are in-app prompts to the user from Leanplum. The interaction of that prompt will be kept and sent ot Leanplum backend.
+Such as "Accept" and "Show".
+List of current messages are:
+
+
+Technical notes
+~~~~~~~~~~~~~~~
+
+Build flags controlling the Leanplum SDK integration
+==================================================
+
+To test this locally, add lines like:
+
+export MOZ_ANDROID_MMA=1
+ac_add_options --with-leaplum-sdk-keyfile=/path/to/leaplum-sdk-developer.token
+
+MOZ_ANDROID_MMA depends on MOZ_NATIVE_DEVICES and MOZ_ANDROID_GCM.
+Since Leanplum requires Google Play Services library, those flags are a proxy for it, and enable respectively.
+
+We want to enable MOZ_ANDROID_MMA in Nightly, but only for
+MOZILLA_OFFICIAL builds.  Since MOZILLA_OFFICIAL is still defined in
+old-configure.in, we can't integrate it in
+mobile/android/moz.configure, and therefore we enable using the
+automation mozconfigs.
+
+Technical notes on the Leanplum SDK integration
+=============================================
+
+Just like Adjust, MmaDelegate uses mmaInterface to inject the MmaLeanplumImp and MmaStubImp.
+Constants used by Leanplum is in MmaConstants. Services in AndroidManifest are in
+``mobile/android/base/MmaAndroidManifest_services.xml.in`` which is also injected by build flag
+MOZ_ANDROID_MMA.
+
+Notes and links
+===============
+
+.. _Leanplum web page: http://leanplum.com/
+.. _github repository: https://github.com/Leanplum/Leanplum-Android-SDK