3.0

Hosting AE SDK in your iOS app

In this guide you will learn how to integrate the AE SDK in your iOS app.
The SDK supports starting a chat session with an expert and handling everything around it, including sending and receiving images and videos as well as handling notifications.
By the end of this guide you're going to have a running implementation in your app!

Currently we support iOS 11 and above.
We don't support SwiftUI.

1. Cocoapods

Contact the SDK team (via email or slack) to get a AESDK.podspec file.
Add the AESDK.podspec file to your repository.
Create a Podfile if you don't already have one:

$ cd your-project-directory
$ pod init

To your Podfile add the SDK pod under your main app's target:

pod 'AESDK', :podspec => './AESDK.podspec'

Go back to the terminal and run:

$ pod install

2. Configuring the SDK

SDK setup with your app key

To setup the SDK you will need to call the setupWithAppKey method providing Your SDK App Key.
If you don't have one, please contact the SDK team.

The SDK App Key is used by the AE platform to determine different features related to your integration, for example the color scheme that will be used or which group of experts will support your users.

Follow these steps to set the app key, and push notifications token:

  1. Open your .xcworkspace file with Xcode
 $ open your-project.xcworkspace

We recommand putting all the initialization code in the AppDelegate file.

Start with importing the SDK:

import AESDK
#import <AESDK/Sdk.h>
  1. Call the setupWithAppKey class method on the global AESDK object:

AESDK.setup(withAppKey:appKey)
[AESDK setupWithAppKey: appKey];

setupWithAppKey method

+ (void)setupWithAppKey: (NSString *)appKey;
NameTypeDescriptionDefault
appKey (required)NSString *Your unique SDK App Key---

Authenticating users

You can read about the options you have to authenticate users in here.

Authenticating users using JWT Token

AESDK.signIn(withAuthToken: "your-jwt-token", withUserMetadata: UserMetadata(name:"name"))
[AESDK signIn:"your-jwt-token" withUserMetadata:[[UserMetadata alloc] initWithName:"name"]];
signIn:withUserMetadata method
+ (void)signIn:(NSString *)authToken withUserMetadata:(UserMetadata *)userMetadata;
NameTypeDescriptionDefault
authenticationToken (required)NSString*Your JWT token---
userMetadataUserMetadataDefines the connected user - relevant only for Family Chatnil

Events from the SDK

You can get notified on events raising from the SDK, such as customer actions, expert actions, or technical events such as login events.
A complete list of the available events can be found here.

 Registering to events can be done only BEFORE you call `setupWithAppKey` method.

AESDK.registerEvents(
        self,
        withEvents: ["MESSAGE_SENT", "MESSAGE_RECEIVED", "ACTION", "IMAGE_PREVIEW"])
[AESDK registerEvents:self 
           withEvents:[NSArray arrayWithObjects:@"MESSAGE_SENT", @"MESSAGE_RECEIVED", @"ACTION", @"IMAGE_PREVIEW", nil]];
registerEvents:withEvents method
+ (void)registerEvents: (id<SDKEventsDelegate>)handler withEvents:(NSArray*)names
NameTypeDescriptionDefault
SDKEventsDelegate (required)SDKEventsDelegateEvents handler---
names (required)NSArray *List of events you want to register to---

3. Enabling push notifications

The Anywhere Expert platform supports sending push notifications using APNs.
We use Apple's AuthKey method to create tokens for Apple's push notifications services.
For the SDK to send notifications to your app you will need to :

  1. Provide us with your AuthKey which is a .p8 file generated through the developer portal. Learn how to obtain a key here.
  2. Provide us your app's APNs token.
  3. Handle push notifications.

Register for remote notifications

Make sure that your app registers for remote notifications.
You should have something like this in your app:

func applicationDidBecomeActive(_ application: UIApplication) {
  let center = UNUserNotificationCenter.current()
  // Request permission to display alerts and play sounds.
  center.requestAuthorization(options: [.alert, .sound, .badge]) { (granted, error) in
                                                                  // Enable or disable features based on authorization.
                                                                 }
  UIApplication.shared.registerForRemoteNotifications()
}
- (void)applicationDidBecomeActive:(UIApplication *)application {
    UNUserNotificationCenter *notificationCenter = [UNUserNotificationCenter currentNotificationCenter];
    [notificationCenter requestAuthorizationWithOptions:(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge) completionHandler:^(BOOL granted, NSError * _Nullable error) {
        // Enable or disable features based on authorization.
    }];
    [application registerForRemoteNotifications];
}

Provide your APNs Token

Once you got your app's APNs token you need to send it to the SDK by calling setApnsToken

AESDK.setApnsToken('apns-token', withBundleId: 'app-bundle-id')
[AESDK setApnsToken:'apns-token' withBundleId:'app-bundle-id'];
setApnsToken:withBundleId method
+ (void)setApnsToken:(NSString*)apnsToken withBundleId: (NSString*)bundleId;
NameTypeDescriptionDefault
apnsToken (required)NSString*Apple Push Notification service token---
bundleId (required)NSString*Your app's unique identifier, read more about it here---

Handle push notifications

The app will receive a push notification whenever the service sends a message to the user.
The SDK can handle these notifications by popping up the chat view and showing the latest message.

A notification will be displayed to the user in 2 cases:

  1. The app is in the foreground but not in the SDK's chat view.
  2. The app is in the background.

To enable this behavior you need to add the following code to your notifications handlers:

App in foreground

To handle push notifications when the app is in the foreground, in your foreground notifications handler add this code:

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    if (!AESDK.handleForegroundPushNotification(userInfo, withCompletionHandler: completionHandler)) {
        // It's not AE notification - handle it yourself
    }
}
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {

    if (![AESDK handleForegroundPushNotification:notification.request.content.userInfo 
                           withCompletionHandler: completionHandler]) {
        // It's not AE notification - handle it yourself
    }
}
handleForegroundPushNotification:withCompletionHandler method
+ (BOOL)handleForegroundPushNotification:(NSDictionary *)userInfo withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler;
NameTypeDescriptionDefault
userInfo (required)NSDictionary *Custom information associated with the notification.
see UNNotificationContent for more info		---
completionHandler (required)void (^)(UNNotificationPresentationOptions options)The block to execute with the presentation option for the notification. Read more about it in Apple's documentation---

App in background

To handle notifications when the app is in the background, in your background notifications handler (not to be confused with silent notifications/background fetch) add the following code:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    if (!AESDK.handlePushNotification(userInfo)) {
        // It's not AE notification - handle it yourself
    }
}
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(nonnull void (^)(UIBackgroundFetchResult))completionHandler {
    if (![AESDK handlePushNotification:userInfo]) {
        // It's not AE notification - handle it yourself
    }
}
handlePushNotification method
+ (BOOL)handlePushNotification:(NSDictionary *)userInfo;
NameTypeDescriptionDefault
userInfo (required)NSDictionary *Custom information associated with the notification.
see UNNotificationContent for more info		---

4. Starting a chat session

All you have to do is call a single function:

AESDK.showChatView()
[self showChatView]

When you call this function a view with a chat should appear.

5. Testing the app

At this point you should be able to open a chat session.

The result will look similar to:

To test the SDK you can chat with our bot by typing ~simbot text. As a result the bot with answer with automated messages.

Associated Types

UserMetadata

-(instancetype) initWithName:(NSString*)name 
                withImageUrl:(NSString* _Nullable)imageUrl 
                 withGroupId:(NSString * _Nullable)groupId;

Parameters

NameTypeDescriptionDefault
name (required)NSString *the user's display name (will appear as part of the message)---
imageUrlNSString *Users avatarnil
groupIdNSString *The id of the group the user is part ofnil

SDKEventsDelegate

@protocol SDKEventsDelegate <NSObject>
- (void)eventEmitted:(NSString*) eventName withArguments:(NSDictionary*)arguments;
@end

Parameters

NameTypeDescriptionDefault
eventNameNSString *Name of the raising event---
argumentsNSDictionary *List of arguments that are relevant to the raising eventEmpty NSDictionary
Last updated on 5/20/2021 by gilm123
← Hosting AE SDK in your React-Native appHosting AE SDK in your Android app →