Class Evergage

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

1public abstract class Evergage
2extends java.lang.Object

Tracking user interactions must ideally be done from an Activity using getScreenForActivity(Activity) rather than getGlobalContext(). For more information on the APIs involved, see Context.

1. Initialize Personalization via initialize(Application) in your custom Application implementation, within Application.onCreate().
2. 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.
3. Determine whether your user has consented to the services. If yes, provide the app’s Personalization configuration and start Personalization using start(ClientConfiguration). Ideally, perform this step as soon as the user’s authenticated ID is known and before the user begins interacting with your app.
4. If your app needs a stable anonymous ID before making an outbound request, use start(ClientConfiguration, OnSdkReadyListener) and read getAnonymousId() from the callback.

1// In MyApplication.java:
2import com.evergage.android.Evergage;
3
4public class MyApplication extends Application {
5@Override
6    public void onCreate() {
7        super.onCreate();
8
9        // Initialize Evergage:
10        Evergage.initialize(this);
11        Evergage evergage = Evergage.getInstance();
12
13        // Recommended to set the authenticated user's ID as soon as known:
14        evergage.setUserId("theAuthenticatedUserId");
15
16        // Start Evergage with your Evergage Configuration:
17        evergage.start(new ClientConfiguration.Builder()
18            .account("yourEvergageAccount")
19            .dataset("yourEvergageDataset")
20            .usePushNotifications(true)
21            .build());
22
23        // ... existing code from your app starts here
24    }
25}

To add information about the user, see setUserId(String) and setUserAttribute(String, String). In the preceding examples, setting the userId provides Personalization with the user’s authenticated ID. This method could also have been called later, if the user’s ID wasn’t 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 or debuggable builds, the app can be configured to use its Personalization-generated URL Scheme. For more information, see EvergageActivity and the Testing guide.

After start(ClientConfiguration) is called at app launch, the Personalization client tracks user activity, sends any applicable events to the Personalization server, and receives campaigns in response. Personalization monitors network availability, stores events if necessary, and reports such events when the network is available again.

After start() returns, the SDK loads persisted state (including the anonymous ID) from disk asynchronously. If your app needs to read getAnonymousId() before making an outbound request, use start(ClientConfiguration, OnSdkReadyListener) and wait for OnSdkReadyListener.onSdkReady() on the main thread.

Once persisted state is loaded, the SDK fetches server configuration. Events become campaign-eligible only after this fetch completes. To check readiness, use isServerConfigLoaded(). To observe readiness on the main thread, use addOnServerConfigLoadedListener(OnServerConfigLoadedListener).

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 (such as View, Comment, Purchase, and so on) and also how they relate to each other (categories, brands, keywords, and so on). For more information, see the Tracking guide and Context.

Campaigns can be served in response to actions generated by the user interacting with the app:

• Personalization automatically handles In-App Message campaigns.
• “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.

1public Evergage()

1@MainThread
2public static void initialize(@NonNull android.app.Application application)

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.

Parameters

1@NonNull
2public static Evergage getInstance()

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

Returns

The Personalization singleton.

1public abstract void start(@NonNull ClientConfiguration clientConfiguration)

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.

Parameters

Since

1.3.0

See Also

• ClientConfiguration
• reset()

1public abstract void start(@NonNull ClientConfiguration clientConfiguration, @NonNull Evergage.OnSdkReadyListener listener)

Starts Personalization with the specified configuration and invokes listener once the SDK completes loading the persisted state from disk.

This overload functions similar to start(ClientConfiguration), with the additional Evergage.OnSdkReadyListener callback. Use this overload when your app needs a signal that the anonymous ID is stable before proceeding. For example, before passing getAnonymousId() to an outbound request.

There is no need to delay ordinary call tracking (trackAction, viewItem, and so on) until this callback is made. The SDK defers relevant auto-events until the anonymous ID is stable.

1evergage.start(new ClientConfiguration.Builder()
2     .account("yourEvergageAccount")
3     .dataset("yourEvergageDataset")
4     .build(), new Evergage.OnSdkReadyListener() {
5         @Override
6         public void onSdkReady() {
7             // Anonymous ID is now stable — safe to pass to outbound requests.
8             String anonId = evergage.getAnonymousId();
9         }
10     });

Parameters

Since

1.5.0

See Also

• start(ClientConfiguration)
• OnSdkReadyListener
• reset

1public abstract void start(@NonNull String accountKey, @NonNull String dataset)

Parameters

See Also

• reset()

1public abstract void reset()

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

1// If the app is changing to a different server environment and a different Personalization dataset is desired..
2// Reset Personalization just before changing the environment:
3Evergage evergage = Evergage.getInstance();
4evergage.reset();
5
6// ... app changes server environment
7
8// Start Personalization again with the dataset to use with the new environment:
9// See Evergage class doc for full example code.
10evergage.setUserId(...);
11evergage.start(...);

User Logout / Consent Revocation

Also call reset() when a user logs out or revokes consent. After reset, the SDK returns to a pre-start state. Tracking calls are dropped until start(ClientConfiguration) is called again.

1// On user logout or consent revocation:
2Evergage evergage = Evergage.getInstance();
3evergage.reset();
4
5// ... user is on login or consent screen; tracking calls during this window are dropped ...
6
7// When a user is ready and consent has been obtained:
8evergage.setUserId(newUserId);
9evergage.start(clientConfiguration);

1public abstract boolean isServerConfigLoaded()

Returns true when the SDK starts and successfully loads server configuration. This means that the events are campaign-eligible.

You can call this method from any thread. However, to perform the check-and-listen pattern, call addOnServerConfigLoadedListener(Evergage.OnServerConfigLoadedListener) on the main thread.

This state resets to false on reset(), or if the SDK is disabled by the server.

Returns

true if server configuration is loaded and events are campaign-eligible.

Since

1.5.0

See Also

• OnServerConfigLoadedListener
• addOnServerConfigLoadedListener(Evergage.OnServerConfigLoadedListener)

1public abstract void addOnServerConfigLoadedListener(@NonNull Evergage.OnServerConfigLoadedListener listener)

Registers a listener to call when the SDK loads its server configuration.

If configuration is already loaded, the listener is called immediately on the main thread.

Multiple listeners may be registered. Listeners are held via strong reference and must be removed using removeOnServerConfigLoadedListener(Evergage.OnServerConfigLoadedListener) to avoid leaks.

To avoid a race where state changes between the check and registration, perform the check-and-register pattern (isServerConfigLoaded() and this method) on the main thread.

Parameters

Since

1.5.0

See Also

• isServerConfigLoaded()
• removeOnServerConfigLoadedListener(Evergage.OnServerConfigLoadedListener)

1public abstract void removeOnServerConfigLoadedListener(@NonNull Evergage.OnServerConfigLoadedListener listener)

Removes a previously registered server-config-loaded listener.

Parameters

Since

1.5.0

See Also

• addOnServerConfigLoadedListener(OnServerConfigLoadedListener)

1@Nullable
2public abstract String getUserId()

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

Returns

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

See Also

• setUserId(String)

1public abstract void setUserId(@Nullable String userId)

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

See Also

• getUserId()
• getAnonymousId()

1@Nullable
2public abstract String 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()

1public abstract void setUserAttribute(@NonNull String attributeName, @Nullable String attributeValue)

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

1@Nullable
2public abstract String getAccountId()

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

Returns

User’s account ID.

See Also

• setAccountId(String)

1public abstract void setAccountId(@Nullable String accountId)

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.

Parameters

See Also

• getAccountId()

1public abstract void setAccountAttribute(@NonNull String attributeName, @Nullable String attributeValue)

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

1public abstract void setFirebaseToken(String token)

If the app uses Firebase Cloud Messaging, provide the Firebase token to Personalization to support Personalization push notification campaigns.

Example code:

1// From MessagingService implementation:
2// Note, onNewToken is not called on every app start, only when token actually changes, which is rare.
3@Override
4public void onNewToken(String token) {
5    super.onNewToken(token);
6    Evergage.getInstance().setFirebaseToken(token);
7}
8// Since the above is rarely called, and might be called before user grants permission,
9// also execute this upon app launch, and ideally on change of related user permission:
10FirebaseMessaging.getInstance().getToken().addOnSuccessListener(token -> Evergage.getInstance().setFirebaseToken(token));

This method will have no effect if you do not enable support for push notifications. For more information, see ClientConfiguration.usePushNotifications).

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

Since:

1.3.0

See Also

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

1@MainThread
2@Nullable
3public abstract Screen getScreenForActivity(@NonNull android.app.Activity activity)

A Screen 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 getGlobalContext().

This method may return null if:

• The Personalization Android SDK was not initialized in the application’s onCreate()
• This method is called from outside the main thread
• The Activity is ignorable
• This method is called before the Activity’s super.onCreate() call, or after super.onDestroy call

Parameters

Returns

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

1@Nullable
2public abstract Context getGlobalContext()

A 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). The 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 Fragment per app screen
• If your app uses a development framework that doesn’t produce an accessible Activity per screen
• If your app uses a decoupled architecture where no Activity is easily accessible

When using 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 null value for the item parameter: viewItem(null).
• Remove the CampaignHandler at 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 null value for the handler: setCampaignHandler(null, "sameTargetUsedEarlier").
  • 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.

Returns

A non-Screen global Context for tracking and personalization. null if the Personalization SDK is disabled or not initialized.

See Also

• getScreenForActivity(Activity)

1public abstract boolean processIntent(@NonNull android.content.Intent intent)

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.

Test URL formats

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

1public static void setLogLevel(int logLevel)

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:

1if (BuildConfig.DEBUG) {
2    Evergage.setLogLevel(LogLevel.INFO);
3}

Parameters

Callback interface notified when the SDK has finished loading persisted state from disk and is fully ready to track with a stable anonymous ID.

Use this listener when your app needs to read getAnonymousId() before making an outbound request.

1public static interface Evergage.OnSdkReadyListener

1void onSdkReady()

Called on the main thread once persisted state has loaded and the anonymous ID is stable.

Since

1.5.0

See Also

• start(ClientConfiguration, OnSdkReadyListener)
• OnServerConfigLoadedListener

Listener notified when server configuration has loaded and events are campaign-eligible.

1public static interface Evergage.OnServerConfigLoadedListener

1void onServerConfigLoaded(@NonNull Evergage evergage)

Called on the main thread when server configuration has loaded and events are campaign-eligible.

This callback can fire more than once, for example after reset() and restart, or if the server disables and then re-enables the SDK.

Parameters

Since

1.5.0

See Also

• isServerConfigLoaded()
• addOnServerConfigLoadedListener(Evergage.OnServerConfigLoadedListener)