Interface Context

Provides APIs to handle data campaigns, track Item views and interactions, and track manual actions, all within a lifecycle-managed context such as Screen.

Typically used as Evergage.getScreenForActivity(android.app.Activity), and if necessary, Evergage.getGlobalContext() for behavior outside of an Activity.

Method	Modifier and Type	Description
addToCart(LineItem lineItem)	void	Tracks that a line item is being added to the shopping cart.
removeFromCart	void	Tracks that a line item is being removed from the shopping cart.
viewCart	void	Tracks an entire shopping cart, which will update/replace the entire state of the mirrored cart in Personalization.
comment(Item item)	void	Tracks that an item was commented on.
favorite(Item item)	void	Tracks that an item was marked by the user as a favorite item.
isActive()	boolean	If this context is currently active or not.
purchase(Order order)	void	Tracks that an order was purchased.
review(Item item)	void	Tracks that an item was reviewed, with no additional details.
review(Item item, Review reviewDetails)	void	Tracks that an item was reviewed, with the contents (optional) of the review.
setCampaignHandler(CampaignHandler handler, java.lang.String target)	void	To optionally support custom 'Data' campaigns, register a campaign handler for the app-defined target within this context.
share(Item item)	void	Tracks that an item was shared, for instance by email or on a social network.
trackAction(java.lang.String action)	void	Sends an event to Personalization describing an action to track.
trackClickthrough(Campaign campaign)	void	Tracks a clickthrough for the provided data campaign.
trackClickthrough(android.content.Intent notificationIntent)	void	Track an uncommonly handled push notification clickthrough that can't be automatically tracked.
trackClickthrough(java.util.Map<java.lang.String,java.lang.String> notificationData)	void	Track an uncommonly handled push notification clickthrough that can't be automatically tracked.
trackDismissal(Campaign campaign)	void	Tracks a dismissal for the provided data campaign.
trackImpression(Campaign campaign)	void	Tracks an impression for the provided data campaign.
viewCategory(Category category)	void	Tracks that a category is being viewed.
viewCategory(Category category, java.lang.String actionName)	void	Same as viewCategory(Category) but with a different action name to distinguish this View Category.
viewItem(Item item)	void	Tracks that an item is being viewed.
viewItem(Item item, java.lang.String actionName)	void	Same as viewItem(Item) but with a different action name to distinguish this View Item.
viewItemDetail(Item item)	void	Tracks that the details of an item are being viewed, such as other product images or a specifications tab.
viewItemDetail(Item item, java.lang.String actionName)	void	Same as viewItemDetail(Item) but with a different action name to distinguish this View Item Detail.
viewTag(Tag tag)	void	Tracks that a tag is being viewed.
viewTag(Tag tag, java.lang.String actionName)	void	Same as viewTag(Tag) but with a different action name to distinguish this View Tag.

If this context is currently active or not.

A typical Screen context is active when Screen.isRunning() and the app and user are active.

Besides some initial setup just before becoming visible (setCampaignHandler(com.evergage.android.CampaignHandler, java.lang.String), viewItem(com.evergage.android.promote.Item) etc), activity generally occurs while a context is active. Context activity, in addition to app state and user idleness, can affect campaign delivery. For more information, see setCampaignHandler(com.evergage.android.CampaignHandler, java.lang.String).

Returns

true, if this context is currently active.

To optionally support custom data campaigns, register a campaign handler for the app-defined target within this context. Can set a null handler for a target to clear.

The "target" is an app-defined string that uniquely identifies the payload data schema - what the data represents and its purpose. See Campaign.getTarget().

While the context, app, and user is active, the handler may receive asynchronous callbacks (on the main thread) with campaigns for the target, in response to actions/events sent. The handler code should show/update the campaign to the user, when appropriate. For example code, see CampaignHandler.

Campaigns may be held for delivery while either:

• The context, app, or user is inactive
• No handler is found for the campaign's target within this context

For each context and target, only the most recent campaign will be held.

Lifecycle details:

• For an Activity, it is recommended to always get Evergage.getScreenForActivity(Activity) and call this method just before becoming visible, specifically in onStart(). For example code, see CampaignHandler.
• In order to prevent accidental leaks in the CampaignHandler, a Screen has a limited time to become visible, after which its handlers and held campaigns will be cleared.
• When a screen transitions to not visible onStop(), all handlers and held campaigns are cleared.

Parameters:

Parameter	Description
handler	The campaign handler this context should use for the specified target.
target	App-defined string that uniquely identifies the payload data schema - what the data represents and its purpose. For more information, see Campaign.getTarget().

See Also

• CampaignHandler
• Campaign

Tracks an impression for the provided data campaign. Call this method after showing the campaign to the user or if the campaign would be shown but the user is in the control group. For more information, see Mobile Data Campaigns and CampaignHandler.

Parameters:

Parameter	Description
campaign	The campaign for which an impression should be tracked.

See Also

• CampaignHandler

Tracks a dismissal for the provided data campaign. Call this method after showing the campaign to the user and the user dismissed the campaign. For more information, see Mobile Data Campaigns and CampaignHandler.

Parameter	Description
campaign	The campaign for which a dismissal should be tracked.

See Also

• CampaignHandler

Tracks a clickthrough for the provided data campaign. Call this method after showing the campaign to the user and the user clicked campaign content. For more information, see Mobile Data Campaigns and CampaignHandler.

Parameters

Parameter	Description
campaign	The campaign for which a clickthrough should be tracked.

See Also

• CampaignHandler

Track an uncommonly handled push notification clickthrough that can't be automatically tracked.

Personalization automatically tracks clicks/opens from Firebase notifications received in the background, and from Firebase notifications received in the foreground that your app chooses to handle by launching an activity in the default launchMode "standard" (for example, intent did not have flags such as FLAG_ACTIVITY_CLEAR_TOP). Any Activity using a different launchMode can enable tracking by calling setIntent within onNewIntent, as shown in the following example.

This tracking method may be required if you manually render a notification from the push. For example, if the Firebase notification is received while the app is in the foreground, it is not automatically shown - instead FirebaseMessagingService#onMessageReceived is called. At this point your app can decide if it wants to manually show a notification. For example code using notifications, see trackClickthrough(Intent).

The following code example uses an AlertActivity/Dialog.

Parameters

Parameter	Description
notificationData	Pass remoteMessage.getData(), after it's been manually rendered and clicked.

Since

1.3.0

See Also

• trackClickthrough(Intent)
• ClientConfiguration.usePushNotifications
• Evergage.setFirebaseToken(String)

Track an uncommonly handled push notification clickthrough that can't be automatically tracked.

Personalization automatically tracks clicks/opens from Firebase notifications received in the background, and from Firebase notifications received in the foreground that your app chooses to handle by launching an activity in the default launchMode "standard" (for example, intent did not have flags such as FLAG_ACTIVITY_CLEAR_TOP). Any Activity using a different launchMode can enable tracking by calling setIntent within onNewIntent:.

This tracking method may be required if you manually render a Notification from the push. For example, if the Firebase notification is received while the app is in the foreground, it is not automatically shown - instead FirebaseMessagingService#onMessageReceived is called. At this point your app can decide if it wants to manually show a notification. See trackClickthrough(Map) for an example using an AlertActivity/Dialog.

The following is example code that uses intents for an Activity and BroadcastReceiver.

Parameters

Parameter	Description
notificationIntent	The intent containing extras from the original remoteMessage.getData(), after the notification has been manually rendered and clicked

Since

1.3.0

See Also

• trackClickthrough(Map)
• ClientConfiguration.usePushNotifications
• Evergage.setFirebaseToken(String)

Tracks that an item is being viewed.

Set null to indicate no longer viewing any item/category/tag.

For an Activity Screen, it is recommended to call this method within onStart() or onResume() before super.onResume(), if the item is known at that time.

Personalization will automatically track the time spent viewing the item while the context, app, and user is active. The item will remain the one viewed until viewItem or viewItemDetail(com.evergage.android.promote.Item) are called again.

Parameters

Parameter	Description
item	The item being viewed.

See Also

• viewItem(Item, String)

Same as viewItem(Item) but with a different action name to distinguish this View Item. Only tracks an action if item is non-null.

Parameters

Parameter	Description
item	The item being viewed.
actionName	Optional different action name.

Since

1.3.0

Tracks that the details of an item are being viewed, such as other product images or a specifications tab. Set null to indicate no longer viewing any item/category/tag.

For an Activity Screen, it is recommended to call this method within onStart() or onResume() before super.onResume(), if the item is known at that time.

Personalization will automatically track the time spent viewing the item while the context, app, and user is active. The item will remain the one viewed until this method or viewItem(com.evergage.android.promote.Item) are called again.

Parameters

Parameter	Description
item	The item whose details are being viewed.

See Also

• viewItemDetail(Item, String)

Same as viewItemDetail(Item) but with a different action name to distinguish this View Item Detail.

Only tracks an action if the item is non-null.

Parameters

Parameter	Description
item	The item whose details are being viewed.
actionName	Optional different action name.

Since

1.3.0

Tracks that a category is being viewed.

Set null to indicate no longer viewing any item/category/tag.

For an Activity Screen, it is recommended to call this method within onStart() or onResume() before super.onResume(), if the category is known at that time.

Parameters

Parameter	Description
category	The category being viewed.

See Also

• viewCategory(Category, String)

Same as viewCategory(Category) but with a different action name to distinguish this View Category.

Only tracks an action if the category is non-null.

Parameters

Parameter	Description
category	The category being viewed.
actionName	Optional different action name.

Since

1.3.0

Tracks that a tag is being viewed. Set null to indicate no longer viewing any item/category/tag.

For an Activity Screen, it is recommended to call this method within onStart() or onResume() before super.onResume(), if the tag is known at that time.

Parameters

Parameter	Description
tag	The tag being viewed.

See Also

• viewTag(Tag, String)

Same as viewTag(Tag) but with a different action name to distinguish this View Tag. Only tracks an action if the tag is non-null.

Parameters

Parameter	Description
tag	The tag being viewed.
actionName	Optional different action name.

Since

1.3.0

Tracks that a line item is being added to the shopping cart.

Parameters

Parameter	Description
lineItem	The line item being added. The LineItem.item should be a Product with a set Product.price.

Tracks that a line item is being removed from the shopping cart.

Parameters

Parameter	Description
lineItem	The line item being removed. The LineItem.item should be a Product with a set Product.price.

Since

1.4.0

Tracks an entire shopping cart, which will update/replace the entire state of the mirrored cart in Personalization. A cart can be considered an "open" order. Most carts will not have an orderId, and so the field can be left un-set.

Parameters

Parameter	Description
order	The entire cart being viewed. Each LineItem.item should be a Product with a set Product.price.

Since

1.4.0

Tracks that an order was purchased. If the order contains no lineItems, the lineItems currently in the cart will be used. If orderId is set and multiple purchase events are received for the same orderId, only the first will be used (all others will be ignored.)

Parameters

Parameter	Description
order	The order that was purchased. Each LineItem.item should be a Product with a set Product.price.

Tracks that an item was reviewed, with no additional details. Equivalent of calling review(Item, Review) with null for the optional review details.

Parameters

Parameter	Description
item	The item that was reviewed.

Tracks that an item was reviewed, with the contents (optional) of the review.

Parameters

Parameter	Description
item	The item that was reviewed.
reviewDetails	The optional contents of the review, such as the rating.

Tracks that an item was shared, for instance by email or on a social network.

Parameters

Parameter	Description
item	The item that was shared.

Tracks that an item was commented on. For instance, an article or blog might accept comments.

Parameters

Parameter	Description
item	The item that was commented on.

Tracks that an item was marked by the user as a favorite item. This is an explicit action taken by the user (often indicated by a single star).

Parameters

Parameter	Description
item	The item that was marked as favorite.

Sends an event to Personalization describing an action to track. When considering the action name, remember that datasets encompass multiple platforms and apps. The name can match a corresponding action/behavior from another platform/app. A campaign can use a source rule to be limited to a specific source or set of sources. For information on recommended rules, see Mobile Data Campaigns.

Actions sent from this context (including Item APIs) can potentially receive a campaign in response, delivered to a handler via setCampaignHandler(com.evergage.android.CampaignHandler, java.lang.String).

Parameters

Parameter	Description
action	A short string that identifies the action.