Class Evergage

This class is primarily used to initialize, configure, and start Marketing Cloud Personalization.

Tracking user interactions should typically be done from an Activity. For the APIs, see getScreenForActivity(Activity) and Context.

First initialize Personalization via initialize(Application) in your custom Application implementation, within Application.onCreate(). Call setUserId(String) as soon as the authenticated user ID is known. Finally, provide the app's Personalization configuration and start Personalization using start(ClientConfiguration).

To add information about the user, see setUserId(String) and 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 setAccountId(String) and setAccountAttribute(String, String).

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.

Once 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 Context.

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 setFirebaseToken(String).
• Custom "Data" campaigns are handled by app-defined code. For more information, see Mobile Data Campaigns and Campaign.

Method	Description	Modifier and Type
getAccountId()	Returns the accountId, after set via setAccountId(String)	abstract java.lang.String
getAnonymousId()	The user's anonymous ID, which will be used if no authenticated ID is specified for the user via setUserId(String).	abstract java.lang.String
getGlobalContext()	Typically unused, for tracking behavior outside of an Activity.	abstract Context
getInstance()	Get the Personalization singleton.	static Evergage
getScreenForActivity(android.app.Activity activity)	Gets the Personalization Screen associated with the specified Activity.	abstract Screen
getUserId()	The authenticated user's ID, once set via setUserId(String)	abstract java.lang.String
initialize(android.app.Application application)	Initialize Personalization by providing the Application from onCreate().	static void
processIntent(android.content.Intent intent)	Advanced: Manually provide an Intent to Personalization for processing.	abstract boolean
reset()	Advanced: 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.	abstract void
setAccountAttribute(java.lang.String attributeName, java.lang.String attributeValue)	Sets an attribute (a name/value pair) on the account.	abstract void
setFirebaseToken(java.lang.String token)	If the app uses Firebase Messaging, notify Personalization when the app's Firebase token changes, in order to support Personalization push notification campaigns.	abstract void
setLogLevel(int logLevel)	Allows developers to adjust the threshold level of Personalization messages to log.	static void
setUserAttribute(java.lang.String attributeName, java.lang.String attributeValue)	Sets an attribute (a name/value pair) on the user.	abstract void
setUserId(java.lang.String userId)	The authenticated user's ID.	abstract void
start(ClientConfiguration clientConfiguration)	Starts Personalization with the specified configuration.	abstract void
start(java.lang.String accountKey, java.lang.String dataset)	Deprecated as of 1.3.0	abstract void

Initialize Personalization by providing the Application from 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.

Separate from start(ClientConfiguration), in order to support rare cases where start must be delayed.

Parameters

Parameter	Description
application	The Application from onCreate()

Get the Personalization singleton. Be sure to first call initialize(Application) from the Application's onCreate().

Returns

The Personalization singleton.

Starts Personalization with the specified configuration. Recommended to call 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.

Parameters

Parameter	Description
clientConfiguration	Client-specific Personalization configuration.

Since

1.3.0

See Also

• ClientConfiguration
• reset()

Deprecated, as of 1.3.0. Use start(ClientConfiguration) instead.

Parameters

Parameter	Description
accountKey	Account within Personalization to use.
dataset	Dataset within the Personalization account to use.

See Also

• reset()

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, userId, 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 reset as demonstrated below.

Recommended Usage

The authenticated user's ID, once set via setUserId(String).

Returns

User's authenticated ID, if any, set via setUserId.

See Also

• setUserId(String)

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, see getAnonymousId().

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.
• With 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 null will also setAccountId(String) to null.

Parameters

Parameter	Description
userId	The user's authenticated ID, or null to go back to anonymous.

See Also

• getUserId()
• getAnonymousId()

The user's anonymous ID, which will be used if no authenticated ID is specified for the user via setUserId(String). 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 getUserId() returns null.

Returns

User's anonymous ID, null if Personalization is disabled or not initialized.

See Also

• getUserId()

Sets an attribute (a name/value pair) on the user. The new value will be sent to the Personalization server with the next event.

Parameters

Parameter	Description
attributeName	The name for the user attribute.
attributeValue	The new value of the user attribute, which replaces any existing value. Set null to clear.

Returns the accountId, after set via setAccountId(String).

Returns

User's account ID.

See Also

• setAccountId(String)

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 null.

This is not your main accountKey passed in to start(ClientConfiguration).

Parameters

Parameter	Description
accountId	Optional account the user belongs to.

See Also

• getAccountId()

Sets an attribute (a name/value pair) on the account. The new value will be sent to the Personalization server with the next event.

Parameters

Parameter	Description
attributeName	The name for the account attribute.
attributeValue	The new value of the account attribute, which replaces any existing value. Set null to clear.

If the app uses Firebase Messaging, notify Personalization when the app's Firebase token changes, in order to support Personalization push notification campaigns.

Example code:

This method will have no effect until you enable support for push notifications, see ClientConfiguration.usePushNotifications). When enabled, Personalization will also directly query Firebase Messaging (if present) for the token, but this method provides a timely update should a token change occur.

Personalization will only send push notifications to the most recent user. For more information, see setUserId(String).

While Personalization automatically tracks clicks/opens for typical Firebase push notification, see Context.trackClickthrough(Intent) and Context.trackClickthrough(Map) for when you must call a method to track the click.

For additional information, see Push Notifications

Parameters

Parameter	Description
token	The Firebase token.

Since:

1.3.0

See Also

• ClientConfiguration.usePushNotifications()
• setUserId(String)
• Context.trackClickthrough(Intent)
• Context.trackClickthrough(Map)

Gets the Personalization Screen associated with the specified Activity.

May be null if the Activity is ignorable, if Personalization is not initialized in the application's onCreate(), if not called from main thread, or if called outside the Screen lifecycle.

Personalization automatically creates the Screen for the non-ignorable Activity in its super.onCreate() call, and destroys it in its super.onDestroy() call.

Parameters

Parameter	Description
activity	The activity for which to get an Personalization Screen.

Returns

The Screen associated with the specified Activity, or null as documented above.

Typically unused, for tracking behavior outside of an Activity.

An Activity should instead use the Screen returned by getScreenForActivity(Activity), which automatically cleans up resources and stops timing/tracking on Activity stop/destroy.

Returns

Context to use for tracking behavior outside of an Activity. null if Personalization is disabled.

See Also

• getScreenForActivity(Activity)

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.

However, if 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 launchMode, taskAffinity, etc.

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

Purpose	URL Format	Description
Test all campaigns	<URLScheme>://test/all	In addition to default behavior of showing mobile campaigns in Published state, also show mobile campaigns that are in Test state. All campaign rules will still be active.
Test a specific experience	<URLScheme>://test/<ExpId>	In addition to default behavior of showing mobile campaigns in Published state, also show the particular experience of a mobile campaign, regardless of that campaign's state and rules that normally determine when its shown.
Stop testing	<URLScheme>://test/none	Return to the default behavior of showing mobile campaigns in Published state only.

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 "evgxxxxx").
• <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.

Parameters

Parameter	Description	Returns
intent	The Intent for Personalization to process	true, if the Intent was Personalization-specific

Allows developers to adjust the threshold level of Personalization messages to log. Usage of this method is typically unnecessary. For initial default levels, see LogLevel.

If you're using this method, you may call it before initialize(android.app.Application).

Recommended to use only during development in DEBUG builds:

Parameters

Parameter	Description
logLevel	See LogLevel