Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 345 insertions, 0 deletions

diff --git a/mobile/android/docs/mma.rst b/mobile/android/docs/mma.rst
new file mode 100644
index 0000000000..6d484f6389
--- /dev/null
+++ b/mobile/android/docs/mma.rst
@@ -0,0 +1,345 @@
+.. -*- 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 https://wiki.mozilla.org/Firefox/Kinto 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, Firefox for Android will send the
+  triggers and message interaction history to Leanplum server when available.
+
+
+Where does data sent to the Leanplum 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 Firefox for Android 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::
+
+  // Sent every time when an event is triggered
+  "action" -> "track"                   // track: an event is tracked.
+  "event" -> "Launch"                   // Used when an event is triggered. e.g. E_Saved_Bookmark.
+  "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.
+
+  // Sent when the app starts
+  "action" -> "start"                   // start: Leanplum SDK starts. heartbeat
+  "userAttributes" -> "{                // A set of key-value pairs used to describe the user.
+    "Focus Installed" -> true           // If Focus for Android is installed.
+    "Klar Installed" -> true            // If Klar for Android is installed.
+    "Pocket Installed" -> true          // If Pocket for Android is installed.
+    "Signed In Sync" -> true            // If the user has signed in to Mozilla account.
+    "Default Browser" -> true           // If the user has set Firefox for Android as default browser.
+    "Pocket in Top Sites" -> true       // If Pocket recommendations for Top Sites home panel are enabled (by default or through user action)
+  }
+  "appId" -> "app_6Ao...."              // Leanplum App ID.
+  "clientKey" -> "dev_srwDUNZR...."     // Leanplum client access key.
+  "systemName" -> "Android OS"          // Fixed String in SDK.
+  "locale" -> "zh_TW"                   // System Locale.
+  "timezone" -> "Asia/Taipei"           // System Timezone.
+  "versionName" -> "55.0a1"             // Firefox for Android version.
+  "systemVersion" -> "7.1.2"            // System version.
+  "deviceModel" -> "Google Pixel"       // System device model.
+  "timezoneOffsetSeconds" -> "28800"    // User timezone offset with PST.
+  "deviceName" -> "Google Pixel"        // System device name.
+  "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 Leanplum Inbox message(Leanplum feature) count.
+  "includeDefaults" -> "false"          // Not used. Always false.
+
+  // Other life cycle actions
+  "action" -> "heartbeat"               // heartbeat: every 15 minutes when app is in the foreground
+                                        // pauseSession: when app goes to background
+                                        // resumeSession: when app goes to foreground
+
+  // Sent for every action
+  "userId" -> "b13b3c239d01aa7c"        // Set by Firefox for Android, we use random uuid so users are anonymous to Leanplum.
+  "deviceId" -> "b13b3c239d01aa7c"      // Same as above.
+  "sdkVersion" -> "2.2.2-SNAPSHOT"      // Leanplum SDK version.
+  "devMode" -> "true"                   // If the SDK is in developer mode. For official builds, it's false.
+  "time" -> "1.497595093902E9"          // System time in second.
+  "token" -> "nksZ5pa0R5iegC7wj...."    // Token come from Leanplum backend.
+
+
+  "gcmRegistrationId" -> "APA91...."    // Send GCM token to Leanplum backend. This happens separately when Leanplum SDK gets initialized.
+
+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 Firefox for Android 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.
+There are three elements that are used for each event. They are: event name, value(default: 0.0), and info(default: "").
+Default value for event value is 0.0. Default value for event info is empty string.
+
+List of current Events related data that is sent:
+
+* When a page could be reader mode and is visible to the user
+
+.. code-block:: json
+
+    {
+      "event": "E_Reader_Available"
+    }
+
+* Download videos or any other media
+
+.. code-block:: json
+
+    {
+      "event" : "E_Download_Media_Saved_Image"
+    }
+
+* Save password and login from door hanger
+
+.. code-block:: json
+
+    {
+      "event" : "E_Saved_Login_And_Password"
+    }
+
+* Save a bookmark from Firefox for Android menu
+
+.. code-block:: json
+
+    {
+      "event" : "E_Saved_Bookmark"
+    }
+
+* Load the bookmark from home panel
+
+.. code-block:: json
+
+    {
+      "event" : "E_Opened_Bookmark"
+    }
+
+* Interact with search url area
+
+.. code-block:: json
+
+    {
+      "event" : "E_Interact_With_Search_URL_Area"
+    }
+
+* Interact with search widget
+
+.. code-block:: json
+
+    {
+      "event" : "E_Interact_With_Search_Widget"
+    }
+
+* When a screenshot is taken
+
+.. code-block:: json
+
+    {
+      "event" : "E_Screenshot"
+    }
+
+* Open a new tab
+
+.. code-block:: json
+
+    {
+      "event" : "E_Opened_New_Tab"
+    }
+
+* App start but Firefox for Android is not set as default browser
+
+.. code-block:: json
+
+    {
+      "event" : "E_Launch_But_Not_Default_Browser"
+    }
+
+* General app start event
+
+.. code-block:: json
+
+    {
+      "event" : "E_Launch_Browser"
+    }
+
+* The user just dismissed on-boarding
+
+.. code-block:: json
+
+    {
+      "event" : "E_Dismiss_Onboarding"
+    }
+
+* Sign in Firefox Account
+
+.. code-block:: json
+
+    {
+      "event" : "E_User_Signed_In_To_FxA"
+    }
+
+* Firefox Sync finished event
+
+.. code-block:: json
+
+    {
+      "event" : "E_User_Finished_Sync"
+    }
+
+* The user just resumed the app from background
+
+.. code-block:: json
+
+    {
+      "event" : "E_Resumed_From_Background"
+    }
+
+* User set Firefox for Android as default browser and resumed the app
+
+.. code-block:: json
+
+    {
+      "event" : "E_Changed_Default_To_Fennec"
+    }
+
+* User installed the Focus app
+
+.. code-block:: json
+
+    {
+      "event" : "E_Just_Installed_Focus"
+    }
+
+* User installed the Klar app
+
+.. code-block:: json
+
+    {
+      "event" : "E_Just_Installed_Klar"
+    }
+
+* User accessed the promo webpage for the Awesomescreen's Firefox promo banner.
+
+.. code-block:: json
+
+    {
+      "event" : "E_Opened_Firefox_Promo"
+    }
+
+* User dismissed the Awesomescreen's Firefox promo banner.
+
+.. code-block:: json
+
+    {
+      "event" : "E_Dismissed_Firefox_Promo"
+    }
+
+Deep Links:
+Deep links are actions that can point Firefox for Android to open certain pages or load features such as `show bookmark list` or
+`open a SUMO page`. When users see a prompt Leanplum message, they can click the button(s) on it. These buttons can
+trigger the following deep links:
+
+* Link to open pages specifically in Firefox for Android (firefox://open?url=)
+* Link to Set Default Browser settings (firefox://default_browser)
+* Link to specific Add-on page (http://link_to_the_add_on_page)
+* Link to sync signup/sign in (firefox://sign_up)
+* Link to default search engine settings (firefox://preferences_search)
+* Link to “Save as PDF” feature (firefox://save_as_pdf)
+* Take user directly to a Sign up for a newsletter (http://link_to_newsletter_page)
+* Link to bookmark list (firefox://bookmark_list)
+* Link to history list (firefox://history_list)
+* Link to main preferences (firefox://preferences)
+* Link to privacy preferences (firefox://preferences_privacy)
+* Link to notifications preferences (firefox://preferences_notifications)
+* Link to accessibility preferences (firefox://preferences_accessibility)
+* Link to general setting (firefox://preferences_general)
+* Link to home page setting (firefox://preferences_home)
+
+Messages :
+Messages are prompts to the user from Leanplum. Messages can be in-app prompts or push notifications. The interaction of that prompt will be kept and sent to Leanplum backend (such
+as "Accept" and "Show"). A messages is a combination of an Event and a Deep Link. The combinations are downloaded from Leanplum
+when Leanplum SDK is initialized. When the criteria is met (set in Leanplum backend, could be when an event happens a certain number of times,
+and/or targeting certain user attribute ), a prompt message will show up. And there may be buttons for users to click. Those clicks
+may trigger deep links.
+
+We use another Mozilla's Google Cloud Messaging(GCM) sender ID to send push notifications.
+These push notifications will look like the notifications that Sync sends out.
+Sender ID let GCM knows Mozilla is sending push notifications via Leanplum.
+GCM will generate a token at client side. We'll send this GCM token to Leanplum so Leanplum knows whom to send push notifications.
+This token is only useful to Mozilla's sender ID so it's anonymized to other parties.
+Push Notifications can be triggered by Events, or be sent by Mozilla marketing team manually.
+
+The list of current messages for Android can be found here: https://wiki.mozilla.org/Leanplum_Contextual_Hints#Android
+
+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-leanplum-sdk-keyfile=/path/to/leanplum-sdk-developer.token
+
+MOZ_ANDROID_MMA depends on MOZ_ANDROID_GOOGLE_PLAY_SERVICES 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/
+* Leanplum SDK github repo: https://github.com/Leanplum/Leanplum-Android-SDK