Evergage Class Reference

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.

1// In AppDelegate.m
2#import <Evergage/Evergage.h>
3
4- (BOOL)application:(UIApplication *)application willFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
5
6    Evergage *evergage = [Evergage sharedInstance];
7
8    #ifdef DEBUG
9    evergage.logLevel = EVGLogLevelWarn;
10    #endif
11
12    // Recommended to set the authenticated user's ID as soon as known:
13    evergage.userId = @"theAuthenticatedUserId";
14
15    // If using Firebase Messaging, be sure to uncomment and do these before starting Evergage:
16    // [FIRApp configure];
17    // [FIRMessaging messaging].delegate = self; // Or whatever your delegate is
18
19    // Start Evergage with your Evergage Configuration:
20    [evergage startWithClientConfiguration:^(EVGClientConfigurationBuilder * _Nonnull builder) {
21        builder.account = @"yourEvergageAccount";
22        builder.dataset = @"yourEvergageDataset";
23        builder.usePushNotifications = YES; // If you want to use Evergage push notification campaigns
24    }];
25
26    // ... existing code from your app starts here
27
28    return YES;
29}

1// In AppDelegate.swift:
2import Evergage
3
4func application(_ application: UIApplication, willFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
5
6    let evergage = Evergage.sharedInstance()
7
8    // For the DEBUG conditional to work in Swift, you must edit your project/target's Build Settings:
9    // Expand "Other Swift Flags" and add "-DDEBUG" under Debug. Do not add to Release!
10    #if DEBUG
11    evergage.logLevel = EVGLogLevel.warn
12    #endif
13
14    // Recommended to set the authenticated user's ID as soon as known:
15    evergage.userId = "theAuthenticatedUserId"
16
17    // If using Firebase Messaging, be sure to uncomment and do these before starting Evergage:
18    // FirebaseApp.configure()
19    // Messaging.messaging().delegate = self // Or whatever your delegate is
20
21    // Start Evergage with your Evergage Configuration:
22    evergage.start { (clientConfigurationBuilder) in
23        clientConfigurationBuilder.account = "yourEvergageAccount"
24        clientConfigurationBuilder.dataset = "yourEvergageDataset"
25        clientConfigurationBuilder.usePushNotifications = true // If you want to use Evergage push notification campaigns
26    }
27
28    // ... existing code from your app starts here
29
30    return true
31}

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.

1+ (nonnull instancetype)sharedInstance

Return Value

The Personalization singleton instance.

Declared In

Evergage.h

Starts Personalization with the specified configuration.

1- (void)startWithClientConfiguration:(nonnull EVGClientConfigurationBlock)configurationBlock

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

Availability

1.3.0

See Also

• EVGClientConfigurationBuilder
• reset

Declared In

Evergage.h

1- (void)startWithEvergageAccountKey:(nonnull NSString *)accountKey dataset:(nonnull NSString *)dataset

Parameters

See Also

• startWithClientConfiguration:

Declared In

Evergage.h

Returns YES when the SDK has started and successfully loaded its server configuration, which means that the events sent are campaign-eligible.

1@property (readonly, nonatomic) BOOL isServerConfigLoaded

You can call this property from any thread. However, for the check-and-observe pattern, perform the isServerConfigLoaded check and notification observation on the main thread in the same call frame. EVGNotificationServerConfigLoaded is posted synchronously on the main thread, and this pattern avoids a race window between the check and addObserver:.

This property resets to NO on reset or if the SDK is disabled by the server.

Observe that EVGNotificationServerConfigLoaded is notified when the server configuration is loaded.

Availability

1.5.0

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.

1@property (nullable, atomic, copy) NSString *userId

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.

1@property (nullable, readonly) NSString *anonymousId

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.

1@property (nullable, atomic, copy) NSString *accountId

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.

1- (void)setUserAttribute:(nullable NSString *)attributeValue forName:(nonnull NSString *)attributeName

Parameters

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.

1- (void)setAccountAttribute:(nullable NSString *)attributeValue forName:(nonnull NSString *)attributeName

Parameters

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.

1@property (nullable, readonly) EVGContext *globalContext

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.

1@property EVGLogLevel logLevel

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.

1- (void)reset

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:

1// If the app is changing to a different server environment and a different Personalization dataset is desired..
2
3// Reset Personalization iOS SDK just before changing the environment:
4Evergage *evergage = [Evergage sharedInstance];
5[evergage reset];
6
7// ... app changes server environment
8
9// Start Personalization iOS SDK again with the dataset to use with the negitw environment:
10// See Evergage class doc for full example code.
11evergage.userId = ...;
12[evergage startWithClientConfiguration:...];

User Logout / Consent Revocation:

Call reset when a user logs out or revokes consent. After reset, the SDK remains in a pre-start state: no device identifiers are read, no events are queued or sent until startWithClientConfiguration: is called again. This state protects against capturing events between sessions and ensures no identifiers or unsent events from the departing user persist into the next session.

1// On user logout or consent revocation:
2Evergage *evergage = [Evergage sharedInstance];
3[evergage 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.userId = newUserId;
9[evergage startWithClientConfiguration:...];

Declared In

Evergage.h

1- (void)allowDesignConnections

Discussion

Recommended to use only during development in DEBUG builds.

See Also

• startWithClientConfiguration:
• [EVGClientConfigurationBuilder useDesignMode]

Declared In

Evergage.h