Skip to content

Home

Jump to bottom
LasOri edited this page Jul 5, 2019 · 60 revisions

Contents

1. First steps

1.1 Initialization

To configure the SDK, the following has to be done in the AppDelegate of the application:

Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    EMSConfig *config = [EMSConfig makeWithBuilder:^(EMSConfigBuilder *builder) {
        [builder setMobileEngageApplicationCode:<applicationCode: NSString>
                            applicationPassword:<applicationPassword: NSString>];
        [builder setContactFieldId:<contactFieldId: NSNumber>];
        [builder setMerchantId:<predictMerchantId: NSString>];
    }];
    [Emarsys setupWithConfig:config];

    return YES;
}
Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    let config = EMSConfig.make { builder in
        builder.setMobileEngageApplicationCode(<applicationCode: String>, applicationPassword: <applicationPassword: String>)
        builder.setContactFieldId(<contactFieldId: Number>)
        builder.setMerchantId(<predictMerchantId: String>)
    }
    Emarsys.setup(with: config)

    return true
}

1.2 setContact

After application setup is finished, you can use setContact method to identify the user with contactFieldValue.

Objective-C
[Emarsys setContactWithContactFieldValue:<contactFieldValue: NSString>
                         completionBlock:^(NSError *error) {
                         }];
Swift
Emarsys.setContactWithContactFieldValue(<contactFieldValue: String>) { error in
}

1.3 clearContact

When the user signs out, the clearContact method should be used:

Objective-C
[Emarsys clearContactWithCompletionBlock:^(NSError *error) {
}];
Swift
Emarsys.clearContact { error in
}

1.4 trackCustomEvent

If you want to track custom events, the trackCustomEvent method should be used, where the eventName parameter is required, but the other attributes are optional.

Objective-C
[Emarsys trackCustomEventWithName:<eventName: String>
                  eventAttributes:<eventAttributes: NSDictionary<String, String>
                  completionBlock:^(NSError *error) {
                  }];
Swift
Emarsys.trackCustomEvent(withName: <eventName: String>, eventAttributes: <eventAttributes: NSDictionary<String, String>) { error in
}

2. Push

2.1 setPushToken

The pushToken has to be set when it arrives:

Objective-C
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [Emarsys.push setPushToken:deviceToken
               completionBlock:^(NSError *error) {
               }];
}
Swift
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Emarsys.push.setPushToken(deviceToken) { error in
    }
}

2.2 clearPushToken

If you want to remove pushToken for the Contact, you can use clearPushToken

Objective-C
[Emarsys.push clearPushTokenWithCompletionBlock:^(NSError *error) {
}];
Swift
Emarsys.push.clearPushToken { error in
}

2.3 trackMessageOpen

If you want to track whether the push messages have been opened, the trackMessageOpen method should be used. In the simplest case this call will be in the AppDelegate's didReceiveRemoteNotification:fetchCompletionHandler: method:

Objective-C
-(void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [Emarsys.push trackMessageOpenWithUserInfo:userInfo
                               completionBlock:^(NSError *error) {
                               }];
}
Swift
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    Emarsys.push.trackMessageOpen(userInfo: userInfo) { error in
    }
}

3. Inbox

3.1 fetchNotifications

In order to receive the inbox content, you can use the fetchNotifications method.

Objective-C
[Emarsys.inbox fetchNotificationsWithResultBlock:^(EMSNotificationInboxStatus *inboxStatus, NSError *error) {
    if (error) {
        NSLog(error);
    } else {
        NSLog(inboxStatus.notifications);
        NSLog(inboxStatus.badgeCount);
    }
}];
Swift
Emarsys.inbox.fetchNotifications { status, error in
    if let error = error {
        print(error as Any)
    } else if let status = status {
        print("Notifications: \(status.notifications) badgeClount: \(status.badgeCount)")
    }
}

3.2 resetBadgeCount

When your user opened the application inbox you might want to reset the unread count (badge). To do so you can use the resetBadgeCount method.

Objective-C
[Emarsys.inbox resetBadgeCountWithCompletionBlock:^(NSError *error) {
}];
Swift
Emarsys.inbox.resetBadgeCount { error in
}

3.3 trackNotificationOpen

To track the notification opens in inbox, use the following trackNotificationOpen method.

Objective-C
[Emarsys.inbox trackNotificationOpenWithNotification:<notification: EMSNotification>
                                     completionBlock:^(NSError *error) {
}];
Swift
Emarsys.inbox.trackNotificationOpen(with: <notification: EMSNotification>) { error in
}

4. InApp

4.1 pause

When a critical activity starts and should not be interrupted by InApp, pause InApp messages

Objective-C
[Emarsys.inApp pause];
Swift
Emarsys.inApp.pause()

4.2 resume

In order to show inApp messages after being paused use the resume method

Objective-C
[Emarsys.inApp resume];
Swift
Emarsys.inApp.resume()

4.3 setEventHandler

In order to react to an event, triggered from the InApp message, you can register for it using the setEventHandler method.

Objective-C
[Emarsys.inApp setEventHandler:<eventHandler: id<EMSEventHandler>>];
Swift
Emarsys.inApp.eventHandler = <eventHandler: EMSEventHandler>

5. Predict

We won't go into the details to introduce how Predict works, and what are the capabilities, but here we aim to explain the mapping between the Predict commands and our interface. Please visit Predict's documentation for more details.

5.1 Initialization

To use Predict functionality you have to setup your merchantId during the initialization of the SDK. In order to track Predict events you can use the methods available on our Predict interface.

5.2 trackCart

When you want to track the cart items in the basket you can call the trackCart method with a list of CartItems. CartItem is an interface which can be used in your application for your own CartItems and then simply use the same items with the SDK

Objective-C
[Emarsys.predict trackCartWithCartItems:<cartItems: NSArray<EMSCartItem *> *>];
Swift
Emarsys.predict.trackCart(withCartItems: <cartItems: Array<EMSCartItem>>)

5.3 trackPurchase

To report a purchase event you should call trackPurchase with the items purchased and with an orderId

Objective-C
[Emarsys.predict trackPurchaseWithOrderId:<orderId: NSString>
                                    items:<cartItems: NSArray<EMSCartItem *> *>];
Swift
Emarsys.predict.trackPurchase(withOrderId: <orderId: String>, items: <cartItems: Array<EMSCartItem>>)

5.4 trackItemView

If an item was viewed use the trackItemView method with an itemId.

Objective-C
[Emarsys.predict trackItemViewWithItemId:<itemId: NSString>];
Swift
Emarsys.predict.trackItemView(withItemId: <itemId: String>)

5.5 trackCategoryView

When the user navigates between the categories you should call trackCategoryView in every navigation. Be aware to send categoryPath in the required format. Please visit Predict's documentation for more information.

Objective-C
[Emarsys.predict trackCategoryViewWithCategoryPath:<categoryPath: NSString>];
Swift
Emarsys.predict.trackCategoryView(withCategoryPath:<categoryPath: String>)

5.6 trackSearchTerm

To report search terms entered by the contact use trackSearchTerm method.

Objective-C
[Emarsys.predict trackSearchWithSearchTerm:<searchTerm: NSString>];
Swift
Emarsys.predict.trackSearch(withSearchTerm: <searchTerm: String>)

5.7 trackCustomEvent

If you want to track custom events, the trackCustomEvent method should be used, where the eventName parameter is required, but the other attributes are optional.

Objective-C
[Emarsys trackCustomEventWithName:<eventName: NSString>
                  eventAttributes:<eventAttributes: NSDictionary<NSString, NSString>
                  completionBlock:^(NSError *error) {
                  }];
Swift
Emarsys.trackCustomEvent(withName: <eventName: String>, eventAttributes: <eventAttributes: NSDictionary<String, String>) { error in
}

6. DeepLink

Note

For further information please check our DeepLink page.

In order to track email link clicks that opens the application directly with the Emarsys SDK, you need to call trackDeepLink in your AppDelegate's application:continueUserActivity:restorationHandler: method.

Objective-C
-  (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray *__nullable restorableObjects))restorationHandler {
    return [Emarsys trackDeepLinkWith:userActivity sourceHandler:^(NSString *source) {
        NSLog([NSString stringWithFormat:@"Source url: %@", source]);
    }];
}
Swift
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    return Emarsys.trackDeepLink(with: userActivity, sourceHandler: { url in
        if let source = url {
            print(source)
        }
    })
}

The (BOOL) return value of Emarsys.trackDeepLink indicates whether the UserActivity contained a Mobile Engage email deeplink and whether it was handled by the SDK.

The first parameter is the UserActivity that comes from the AppDelegate’s application:continueUserActivity:restorationHandler: method.

The second parameter is optional, it is a closure/block that provides the source Url that was extracted from the UserActivity.

For more information, read the relevant iOS documentation.

Clone this wiki locally