mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-25 19:25:43 +00:00
d4eda07913
MozReview-Commit-ID: 95c9BkvkCbc --HG-- extra : rebase_source : c2f5f3afb7e746948eb903b32f3f26e3cacd2cc6
222 lines
11 KiB
ReStructuredText
222 lines
11 KiB
ReStructuredText
.. -*- 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, Fennec 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 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::
|
|
|
|
// 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 Fennec as default browser.
|
|
}
|
|
"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" // Fennec 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 Fennec, 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 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.
|
|
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
|
|
{
|
|
"event" : "E_Reader_Available"
|
|
}
|
|
* Download videos or any other media
|
|
{
|
|
"event" : "E_Download_Media_Saved_Image"
|
|
}
|
|
* Save password and login from door hanger
|
|
{
|
|
"event" : "E_Saved_Login_And_Password"
|
|
}
|
|
* Save a bookmark from Fennec menu
|
|
{
|
|
"event" : "E_Saved_Bookmark"
|
|
}
|
|
* Load the bookmark from home panel
|
|
{
|
|
"event" : "E_Opened_Bookmark"
|
|
}
|
|
* Interact with search url area
|
|
{
|
|
"event" : "E_Interact_With_Search_URL_Area"
|
|
}
|
|
* When a screenshot is taken
|
|
{
|
|
"event" : "E_Screenshot"
|
|
}
|
|
* Open a new tab
|
|
{
|
|
"event" : "E_Opened_New_Tab"
|
|
}
|
|
* App start but Fennec is not set as default browser
|
|
{
|
|
"event" : "E_Launch_But_Not_Default_Browser"
|
|
}
|
|
* General app start event
|
|
{
|
|
"event" : "E_Launch_Browser"
|
|
}
|
|
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`. 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 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_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/
|
|
* Leanplum SDK github repo: https://github.com/Leanplum/Leanplum-Android-SDK
|