This class is primarily used to initialize, configure, and start Marketing Cloud Personalization.
- Initialize Personalization via
initialize(Application)in your custom Application implementation, within
- Determine if the user is a returning known or authenticated user. If so, call
setUserId(String)as soon as the authenticated user ID is known.
- Determine whether your user has consented to services. If yes, provide the app's Personalization configuration and start Personalization using
start(ClientConfiguration). Ideally, this step should be performed as soon as the user's authenticated ID is known and before the user begins interacting with your app.
To add information about the user, see
setUserAttribute(String, String). In the examples above, setting the
userId provides Personalization with the user's authenticated ID. This could also have been called later, if the user's ID was not known at startup, and would then be sent with subsequent events. Likewise, if your users belong to an account, see
To easily and codelessly manage test campaigns from the device in debug/debuggable builds, the app can be configured to use its Personalization-generated URL Scheme. For more information, see
EvergageActivity and the Testing guide.
start(ClientConfiguration) has been called at app launch, the Personalization client will track user activity, send any applicable events to the Personalization server, and receive campaigns in response. Personalization will monitor network availability and store events if necessary, sending them when the network becomes available again.
For information on tracking screens, see the Tracking guide.
Personalization can track how the user views and interacts with articles, blogs and products which are collectively called items. Personalization understands the actions that are possible on these items (View, Comment, Purchase, etc.) and also how they relate to each other (categories, brands, keywords, etc.). For more information, see the Tracking guide and
Campaigns may be served in response to actions generated by the user interacting with the app:
- "In-App Message" campaigns are automatically handled by Personalization.
- "Push Notification" campaigns require Firebase Cloud Messaging, and some setup. For more information, see Push Notifications and
- Custom "Data" campaigns are handled by app-defined code. For more information, see Mobile Data Campaigns and
|Method||Description||Modifier and Type|
|Returns the |
|The user's anonymous ID, which will be used if no authenticated ID is specified for the user via |
|Get the Personalization singleton.|
|The authenticated user's ID, once set via |
|Initialize Personalization by providing the Application from |
|Advanced: Manually provide an Intent to Personalization for processing.|
|Advanced: Resets Personalization so |
|Sets an attribute (a name/value pair) on the account.|
|If the app uses Firebase Messaging, notify Personalization when the app's Firebase token changes, in order to support Personalization push notification campaigns.|
|Allows developers to adjust the threshold level of Personalization messages to log.|
|Sets an attribute (a name/value pair) on the user.|
|The authenticated user's ID.|
|Starts Personalization with the specified configuration.|
|Deprecated as of 1.3.0|
Initialize Personalization by providing the
onCreate(). This method enables Personalization to follow
Activities, so it may provide activity-related APIs & analytics, and also suspend operations while the app is in the background.
This is a required method.
start(ClientConfiguration), in order to support rare cases where start must be delayed.
Get the Personalization singleton. Be sure to first call
initialize(Application) from the Application's
The Personalization singleton.
Starts Personalization with the specified configuration.
Before calling this method, the app must determine that the user has consented to personalization services. We recommend calling this method from
Application.onCreate(). For example code, see the Startup section in this article. Once started, subsequent calls to start will have no effect, unless
reset() has been called due to an environment change.
|Client-specific Personalization configuration.|
Deprecated, as of 1.3.0. Use start(ClientConfiguration) instead.
|Account within Personalization to use.|
|Dataset within the Personalization account to use.|
This is an advanced method.
Resets Personalization so
start(ClientConfiguration) can be called again with a different dataset, in order to support an app that changes its server environment (production, demo, QA, etc) and wants to change the Personalization dataset accordingly.
Reset will clear settings, unsent actions, held campaigns, test campaign settings,
accountId, and unsent attributes.
Reset will keep existing campaign handlers, current screen visibility and items being viewed, since it would otherwise be cumbersome/confusing to require re-playing lifecycle methods, re-navigating to screens, re-setting items being viewed, etc.
Ideally the app will avoid environment churn:
- On app launch, if the user must select/confirm the environment before using the app, consider delaying the call to
start(ClientConfiguration)to when the environment is chosen and avoid calling reset.
- Otherwise, if the user can immediately use the app with the current environment, call
start(ClientConfiguration)as normal with the corresponding dataset. And when the environment later changes, and a different Personalization dataset is desired, call
resetas demonstrated below.
The authenticated user's ID, once set via
User's authenticated ID, if any, set via
The authenticated user's ID. Setting this is critical to correlate the same user's activity across devices and platforms, and also makes it easier to find a user in Personalization.
When the authenticated ID is null, Personalization identifies the user with a generated anonymous ID. For more information, including how activity may be merged, see
You may call this method with
null to make the user anonymous again. At that point, all new activity will be attributed to the anonymous user, and push notifications can only be sent to the anonymous user (based off the anonymous activity). So after a simple 'log out', you may wish to continue to call this method with the previously-authenticated user ID, to continue to be able to send push notifications to the authenticated user (based off the authenticated activity) etc. You decide when the user becomes truly anonymous again.
We recommend calling this method:
- With the ID, when the user successfully authenticates (logs in).
- With the ID, on app launch, as soon as possible after
initialize(Application), if the user is still authenticated, or previously authenticated but needs to log back in again. Personalization does not persist the ID across app restarts.
null, when the app decides the user should be anonymous again. This may not be on logout - see note about anonymous activity above. Calling this method with
|The user's authenticated ID, or |
The user's anonymous ID, which will be used if no authenticated ID is specified for the user via
The anonymous ID is a UUID generated by Personalization that is unique per app installation. When a user transitions from anonymous to authenticated (via
setUserId(String)), the previous activity while anonymous will be merged into the authenticated user if 'Merge Anonymous Users' is enabled in the Personalization web app.
This ID should be passed in SmartSearch requests if
User's anonymous ID,
null if Personalization is disabled or not initialized.
Sets an attribute (a name/value pair) on the user. The new value will be sent to the Personalization server with the next event.
|The name for the user attribute.|
|The new value of the user attribute, which replaces any existing value. Set |
accountId, after set via
User's account ID.
The optional account this user belongs to. Set this property to track which of your accounts inside the Personalization dataset and account your users belong to. If account is no longer applicable, it can be set to
This is not your main accountKey passed in to
|Optional account the user belongs to.|
Sets an attribute (a name/value pair) on the account. The new value will be sent to the Personalization server with the next event.
|The name for the account attribute.|
|The new value of the account attribute, which replaces any existing value. Set |
If the app uses Firebase Cloud Messaging, provide the Firebase token to Personalization to support Personalization push notification campaigns.
This method will have no effect if you do not enable support for push notifications. For more information, see
Personalization will only send push notifications to the most recent user. For more information, see
While Personalization automatically tracks clicks/opens for typical Firebase push notification, see
Context.trackClickthrough(Map) for when you must call a method to track the click.
For additional information, see Push Notifications
|The Firebase token.|
Context associated with an
Activity for tracking and personalization, when an app can use an
Activity for each screen or page of the app. If your app cannot use an
Activity for each screen or page, you can instead use
This method may return
- The Personalization Android SDK was not initialized in the application's
- This method is called from outside the main thread
- This method is called before the
super.onCreate()call, or after
|The activity for which to get an Personalization Screen.|
Screen associated with the specified
null as documented above.
Context that is not a
Screen for tracking and personalization, when an app can't use an
Activity for each screen or page of the app. If your app can use an
Activity for each screen or page, you can instead use the
Screen returned by
getScreenForActivity(Activity) method automatically cleans up resources and stops timing and tracking when the
Activity is stopped or destroyed.
You can also use the
getGlobalContext() method in the following scenarios:
- If your app uses a
Fragmentper app screen
- If your app uses a development framework that doesn't produce an accessible
- If your app uses a decoupled architecture where no
Activityis easily accessible
globalContext, you lose certain cleanup and safety mechanisms the SDK automatically provides for a
Screen. Therefore, you must manually carry out the following operations, whenever and wherever applicable.
- Stop accumulating view time on an item:
- After invoking any of the View APIs (such as,
Context.viewItem(com.evergage.android.promote.Item)), you must indicate when the item is no longer being viewed by calling the View API again with a
nullvalue for the item parameter:
- After invoking any of the View APIs (such as,
- Remove the
CampaignHandlerat the end of its lifecycle:
- After using
Context.setCampaignHandler(com.evergage.android.CampaignHandler, java.lang.String), you'll need to indicate when to remove the handler by invoking the method again with a
nullvalue for the handler:
- If the handler is associated with a specific screen or UI component of the app, it must be removed when the screen or UI component is being removed. Otherwise, the handler can contain strong references to objects, preventing them from being garbage collected. Additionally, the handler might attempt to handle a campaign, leading to crashes or unexpected behavior caused by the use of UI-related objects beyond their intended lifecycle.
- After using
Context for tracking and personalization.
null if the Personalization SDK is disabled or not initialized.
Advanced: Manually provide an Intent to Personalization for processing.
Typically, this method is not called directly, but instead automatically called by
EvergageActivity to support easily and codelessly managing test campaigns from the device in debug/debuggable builds by opening test URLs in the mobile browser. For more information on testing your campaigns, see Testing.
EvergageActivity is completely removed (not recommended), this method can be used to provide the related URLs to Personalization. Simply provide an
Intent with the desired Uri. If deciding to move the intent filter to an existing app
Activity, be aware that URL handling is another launch point for an
Activity, potentially resulting in multiple instances/tasks with that
Activity, depending on
The URL formats below are not what you type into the mobile browser on the device. For more information on supported URL formats, see Testing. Android typically requires a redirect or link-tap from the mobile browser to trigger the intent-filter. The URL formats below are after that redirect/link.
Test URL formats
|Test all campaigns||In addition to default behavior of showing mobile campaigns in |
|Test a specific experience||In addition to default behavior of showing mobile campaigns in |
|Stop testing||Return to the default behavior of showing mobile campaigns in |
For the URL formats listed in the preceding table:
<URLScheme>is the Personalization-generated URL scheme for the app, which is located in the Personalization UI: Select Dataset, then Settings > Sources > Apps > (this app) > URL Scheme: (format "
<ExpID>is the ID of a specific campaign experience, which can be found in the Personalization UI: Select Dataset, then Campaigns > Campaign Summary of the campaign the experience is in.
- These URLs do not aggregate or combine. The most recent one determines the behavior.
- Testing lasts for 30 minutes, or until app termination or another test URL is entered.
Allows developers to adjust the threshold level of Personalization messages to log. Usage of this method is typically unnecessary. For initial default levels, see
If you're using this method, you may call it before
Recommended to use only during development in