Evergage Class Reference

Inherits from	Declared in
NSObject	EVGContext.h

This class is primarily used to configure and start the Marketing Cloud Personalization iOS SDK.

Tracking user interactions should ideally be done from a UIViewController, see [UIViewController(Evergage) evergageScreen] versus globalContext. To know more about the APIs, see EVGContext.

As early as possible, ideally within UIApplicationDelegate -willFinishLaunchingWithOptions:, do the following.

1. Enable logging in DEBUG builds.
2. Determine if the user is a returning known or authenticated user. If so, set the userId as soon as the authenticated user ID is known, ideally before start.
3. Determine whether the user has consented to services. If yes, provide the app’s Personalization configuration and start Personalization using startWithClientConfiguration:, ideally before the user begins interacting with your app, as shown in the following examples.

To add information about the user, see userId and setUserAttribute:forName:. 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 accountId and setAccountAttribute:forName:.

To easily and codelessly manage test campaigns from the device, the app can add an Personalization URL scheme and define one of the iOS open-url delegate methods, see [Evergage(Swizzling) handleOpenURL:]. For more information on testing your campaigns, see the Testing guide.

Once startWithClientConfiguration: has been called at app launch, the Personalization client will track user activity, send any applicable events to the Personalization server, and support campaigns in response. Personalization will monitor network availability and store events if necessary, sending them when the network becomes available again.

The Personalization client supports automatically tracking UIViewControllers and dynamically mapping and re-mapping them to view actions using the Personalization UI. For more information, see Tracking Guide, UIViewController(Evergage), and EVGScreen.

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

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 APNS setup, and optionally Firebase. For more information , see Push Notifications.
• Custom "Data" campaigns are handled by app-defined code. For more information, see Mobile Data Campaigns and EVGCampaign.

The Personalization singleton instance.

Return Value

The Personalization singleton instance.

Declared In

Evergage.h

Starts Personalization with the specified configuration.

Before calling startWithClientConfiguration:, the app should ensure that the user has actually consented to the services. We recommend calling startWithClientConfiguration: from willFinishLaunchingWithOptions:. For examples on how to do this, see the startup examples in the Startup section of this article. Once started, subsequent calls have no effect unless reset has been called due to an environment change.

Parameters

Parameter	Description
configurationBlock	Client-specific Personalization configuration defined via EVGClientConfigurationBuilder

Availability

1.3.0

See Also

• EVGClientConfigurationBuilder
• reset

Declared In

Evergage.h

Deprecated as of 1.3.0. Use startWithClientConfiguration: instead.

Parameters

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

See Also

• startWithClientConfiguration:

Declared In

Evergage.h

The user’s authenticated ID. Setting this property is critical to correlate the same user’s activity across devices and platforms, and also makes it easier to find a user in Personalization.

Discussion

When the authenticated ID is null, Personalization identifies the user with a generated anonymous ID. See anonymousId for details, including how activity may be merged.

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.

Recommended to set this property:

• With the ID, when the user successfully authenticates (logs in).
• With the ID, on app launch as soon as possible, 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 nil, 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 nil will also set accountId to nil.

See Also

• @property anonymousId

Declared In

Evergage.h

The user’s anonymous ID, via identifierForVendor, which will be used if no authenticated ID is specified for the user via userId.

Availability

1.2.1

Discussion

May return nil if Personalization is disabled.

When a user transitions from anonymous to authenticated (via userId), the previous activity while anonymous will be merged into the authenticated user if Merge Anonymous Users is enabled in the Personalization UI.

This ID should be passed in SmartSearch requests if userId returns nil.

See Also

• @property userId

Declared In

Evergage.h

The optional account this user belongs to. Set this property to track which of your accounts users belong to inside the Personalization dataset and account. If account is no longer applicable, it can be set to nil.

This is not the main Personalization account passed in to startWithClientConfiguration:.

Declared In

Evergage.h

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
attributeValue	The new value of the user attribute, which replaces any existing value. Set nil to clear.
attributeName	The name for the user attribute.

Declared In

Evergage.h

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
attributeValue	The new value of the account attribute, which replaces any existing value. Set nil to clear.
attributeName	The name for the account attribute.

Declared In

Evergage.h

An EVGContext that is not an EVGScreen for tracking and personalization. To be used when an app can't use a UIViewController for each screen or page of the app.

Availability

1.2.0

Discussion

nil if Personalization is disabled.

An app that can use a UIViewController for each screen or page of the app should instead use the EVGScreen returned by [UIViewController(Evergage) evergageScreen], which automatically cleans up resources and stops timing/tracking on UIViewController disappear.

However, some apps might use a development framework that does not produce an accessible UIViewController per screen, or use a decoupled architecture where referencing individual UIViewControllers can be problematic/undesirable. In those scenarios, apps can choose to instead use this globalContext.

Using the globalContext means losing some cleanup/safety mechanisms the SDK automatically provides, and so you must manually do these operations, as applicable:

• Stop accumulating view time on an item.
  • After calling any of the View APIs, you’ll need to indicate when the item is no longer being viewed by calling the a View API method again, supplying nil for the item parameter viewItem:nil.
• Remove the EVGCampaignHandler when its lifecycle should end.
  • After using [EVGContext setCampaignHandler:forTarget:], you'll need to indicate when the handler should be removed by calling it again, supplying nil for the handler parameter, such as setCampaignHandler:nil forTarget:@"sameTargetUsedEarlier".
  • If the campaign handler concerns a particular screen or page of the app, it should be removed when the screen or page would be removed. Otherwise, the handler might contain strong references, preventing objects from being deallocated or released, and possibly even trying to handle a campaign which could result in crashes or unexpected behavior from UI-related objects being used beyond their expected lifecycle.

See Also

• [UIViewController(Evergage) evergageScreen]

Declared In

Evergage.h

Configures the threshold EVGLogLevel of messages to log. Will only log messages at this level of severity or greater.

Discussion

Recommended to set only during development in DEBUG builds.

Declared In

Evergage.h

Resets the SDK so startWithClientConfiguration: can be called again with a different dataset, in order to support apps that change environments (production, demo, QA, etc) and want to change Personalization datasets as well.

Discussion

Reset will clear settings, unsent actions, held campaigns, test campaign settings, allowDesignConnections, userId, accountId, and unsent attributes.

Reset will keep existing campaign handlers, screen visibility, and items being viewed, since it would potentially be cumbersome/confusing to require once again setting handlers, potentially mocking viewWillAppear or 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 startWithClientConfiguration: to when the environment is chosen and avoid calling reset.
• Otherwise, if the user can immediately use the app with the current environment, call startWithClientConfiguration: 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:

Declared In

Evergage.h

Deprecated as of 1.3.0. Instead use startWithClientConfiguration: with [EVGClientConfigurationBuilder useDesignMode].

Discussion

Recommended to use only during development in DEBUG builds.

See Also

• startWithClientConfiguration:
• [EVGClientConfigurationBuilder useDesignMode]

Declared In

Evergage.h