Evergage Class Reference

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

Tracking user interactions should typically be done from a UIViewController, see [UIViewController(Evergage) evergageScreen] and EVGContext for the APIs.

Within UIApplicationDelegate -willFinishLaunchingWithOptions:, first enable logging in DEBUG builds. Set the userId as soon as the authenticated user ID is known. Finally, provide the app’s Personalization configuration and start Personalization using startWithClientConfiguration:, as shown in the following examples.

• Objective C

  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    // Start Personalization with your Personalization Configuration:
  16    [evergage startWithClientConfiguration:^(EVGClientConfigurationBuilder * _Nonnull builder) {
  17        builder.account = @"yourEvergageAccount";
  18        builder.dataset = @"yourEvergageDataset";
  19        builder.usePushNotifications = YES;
  20#ifdef DEBUG
  21        builder.useDesignMode = YES;
  22#endif
  23    }];
  24
  25    // ... existing code from your app starts here
  26
  27    return YES;
  28}

• Swift

  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    // Start Personalization with your Personalization Configuration:
  18    evergage.start { (clientConfigurationBuilder) in
  19        clientConfigurationBuilder.account = "yourEvergageAccount"
  20        clientConfigurationBuilder.dataset = "yourEvergageDataset"
  21        clientConfigurationBuilder.usePushNotifications = true
  22        clientConfigurationBuilder.useDesignMode = true
  23    }
  24
  25    // ... existing code from your app starts here
  26
  27    return true
  28}

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. Recommended to call from willFinishLaunchingWithOptions:. For example code, see the Startup section in this article. Once started, subsequent calls will have no effect, unless reset has been called due to an environment change.

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

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

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

Typically unused, for tracking behavior outside of individual UIViewControllers.

1@property (nullable, readonly) EVGContext *globalContext

Availability

1.2.0

Discussion

nil if Personalization is disabled.

A typical UIViewController-based 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 have decoupled architectures/frameworks 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:
    • [EVGContext viewItem:]
    • [EVGContext viewItem:actionName:]
    • [EVGContext viewItemDetail:]
    • [EVGContext viewItemDetail:actionName:]
    • [EVGContext viewCategory:]
    • [EVGContext viewCategory:actionName:]
    • [EVGContext viewTag:]
    • [EVGContext viewTag:actionName:]
  • You’ll need to indicate when the item is no longer being viewed by calling the method again, supplying nil for the item parameter, such as viewItem:nil;
• Remove the EVGCampaignHandler when its lifecycle should end.
  • By calling [EVGContext setCampaignHandler:forTarget:] again, supplying nil for the handler parameter, such as setCampaignHandler:nil forTarget:@"sameTargetOriginallySetWith"
  • If the campaign handler concerns a particular screen/UI of the app, it should be removed when the screen/UI would be removed. Otherwise the handler might contain strong references, preventing objects from being deallocated/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:...];

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