Interaction - Minodes SDK for iOS

Use the Minodes Interactions SDK to add powerful location-based features to your app, enabling a richer and more interactive shopping experience for your customers. Send your customers messages according to their location, profile and preferences, or build new features on top of iBeacon technology.

Requirements

Application Token

In order to integrate our solution, you need to provide an Application Token to the SDK. To obtain your application token, please contact us.

Apple Push Certificates

In order to send push notifications to your users, we'll need an Apple Push Certificate from you (just e-mail it to us). It needs to be a .p12 file and should not have a password. The certificate also needs to be production ready.

Integrating the SDK in your application

CocoaPods is the recommended way to add the Minodes SDK to your project.

• Add a pod entry to your Podfile pod 'MinodesInteractionsSDK', '~> 0.1.0'
• Install the pod(s) by running pod install.

To make sure, your app can detect beacons in background and receive push notifications, you have to enable at least the following background modes for your app target:

In your Target's Info pane, add a string property 'NSLocationAlwaysUsageDescription' and describe what your application is going to do with the location services (e.g., "Your location is used to enhance your shopping experience with location-specific information and offers."). This text will be displayed to users when asking them to access location services in the background. This setting is necessary to enable background monitoring for beacons.

In your project settings, select the "Build Settings" tab and in "Other Linker Flags" add: -ObjC

Using the SDK

Use the following code to integrated the SDK into your app; add it to the part where you want to start the SDK (the ApplicationDelegate for Example):

[[MINBeaconSDK sharedManager] startSDKWithAppToken:@"app-token"];
[[MINBeaconSDK sharedManager] startMonitoring];
[MINBeaconSDK sharedManager].delegate = self;

You need to replace app-token with your application token (see Requirements above).

To received information from the Minodes backend, set a delegate which conforms to the protocol MINBeaconSDKDelegate in the class where you are going to use the SDK and import the Minodes Beacon SDK manager:

#import <MinodesSDK/MINBeaconSDK.h>

Optional: In order to use custom tags (such as user name, age, etc.) when you define a marketing campaign, you need to send us UserData. UserData is a dictionary of key value pairs; the key is the identifier of the CustomTag and the value is the value of the user using your app.

For example, to define the user as a 20 years old male, do the following:

NSDictionary *dictionary = @{ @"age" : 20,
                              @"gender" : male }    

[MINBeaconSDK sharedManager].userData = dictionary;

UserData doesn't need to be sent each time the application is started. They can be sent only when some value changed.

Handling Notifications

To interact with your user, Minodes Interactions will send push notifications to their device; these push notification will automatically be handled by the SDK.

Therefore, you need to register the device for user notifications, forward the push notification token and forward every push notification to the SDK.

Registering the device:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    if ([application respondsToSelector:@selector(registerUserNotificationSettings:)]) {
        UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:
        (UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert) categories:nil];

        [[UIApplication sharedApplication] registerUserNotificationSettings:settings];

    } else {
        [[UIApplication sharedApplication] registerForRemoteNotificationTypes:
         (UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert)];
    }
}

-(void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings {
    [application registerForRemoteNotifications];
}

Forwarding the push notification token to the SDK:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [[MINBeaconSDK sharedManager] didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

Forwarding push notifications to the SDK:

To forward push notifications while the app is running in the foreground:

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {    
    [[MINBeaconSDK sharedManager] didReceiveRemoteNotification:userInfo];
}   

To forward push notifications while the app is running in the background, add the following code to the method application:didFinishLaunchingWithOptions:

NSDictionary *notificationDict = [launchOptions objectForKey:UIApplicationLaunchOptionsRemoteNotificationKey];
if (notificationDict != nil) {
    [[MINBeaconSDK sharedManager] didReceiveRemoteNotification:notificationDict];
}    

Processing push notifications and respective actions

When a campaign matches the user, the Interactions backend sends a push notification to the device of the user to display an action; an action can open the application, open a specific page of the application, an external url, an image, etc.

These actions are automatically handled by the SDK. However, you are also free to to ask your user before executing an action if that action should be performed at all (e.g. asking for permission before opening an external URL):

Example:

- (void)beaconSDK:(MINBeaconSDK *)beaconSDK shouldPerformAction:(MINAction *)action result:(void (^)(MINActionResponse))result
{
    // ask your user and call the callback
    result(MINActionResponseAllow);
}

The action is of type MINAction and you have access to the following parameters in order to process the current action:

• actionId: The ID of the action.
• type: The action type (external_url, internal_url, alert, image).
• content: The content of the action. A dictionary containing the title of the action (title), the message to display (message), the URL of the action (url) and the URL of an image (url_image). Those parameters are optional and depend on the action type.
• delay: The delay to execute the action.
• receivedAtTimestamp: Timestamp when the action is received.
• status: Current status of the action (e.g. 'accepted').

In the following example, you could see an action with the type external_url (i.e., opening a webpage in Safari):

{
    "app_user_action":
    {
        "id":4784,
        "action_type":"external_url",
        "content":
        {
            "url":"http://www.google.com",
            "message":"Hello world!"
        },
        "delay":0,
        "status":"accepted"
    }
}

Different types of actions:

alert

Display a default alert view in your app.

external_url

Open an URL in an external app (e.g. http://google.com would be opened in Safari).

internal_url

Display a webpage inside the application. This has to be handled by the app itself.

In order to show an internal url, the application must implement the MINBeaconSDKDelegate protocol which declares the following method:

-(void)beaconSDK:(MINBeaconSDK *)beaconSDK handleUrl:(NSURL *)url

The SDK calls this delegate method each time the app should handle an URL.

For example, to display a web page in a UIWebView of the app:

-(void)beaconSDK:(MINBeaconSDK *)beaconSDK handleUrl:(NSURL *)url{
    NSURLRequest *request = [[NSURLRequest alloc] initWithURL:url
                                                  cachePolicy: NSURLRequestUseProtocolCachePolicy
                                              timeoutInterval:30];
    [self.webView loadRequest:request];
}

For example, to display a specific page of your application defined with a custom URL scheme ("myapp://users/123"), you can perform a segue to show a webview or a view controller depending on the URL:

- (void)beaconSDK:(MINBeaconSDK *)beaconSDK handleUrl:(NSURL *)url {
    if([url.scheme isEqualToString:@"http"] || [url.scheme isEqualToString:@"https"]) {
        // Perform a segue that opens a webview
        [self performSegueWithIdentifier:@"webview" sender:self];
    } else if ([url.scheme isEqualToString:@"myapp"]) {
        // Perform a segue to open a UIViewController depending on the host of the URL (In "myapp://users/123", users is the host of the URL)
        [self performSegueWithIdentifier:url.host sender:self];
    }
}

image

Open an image in a UIImageView. The URL of the image has to be handled by the application in the [beaconSDK: handleImage:] method of MINBeaconSDKDelegate.

- (void)beaconSDK:(MINBeaconSDK *)beaconSDK handleImage:(UIImage *)image {
   if(image != nil) {
       UIImageView *imageView = [[UIImageView alloc] initWithImage:image];
   }
}

Test action on users' phones

Minodes Interactions allows users to try out actions on their own phones, which requires linking a user's phone to their Minodes Interactions user account. In order to support this functionality in the application, you'll need a URL Scheme and a URL Identifier provided by Minodes. Please, contact us to obtain them.

In order to implement this functionality in your app, add the following method in the delegate of the application, updating app_scheme with your own URL Scheme:

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
 sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    if ([[url scheme] isEqualToString:@"app_scheme"]) {
        // Forward URL to the SDK
        [[MINBeaconSDK sharedManager] activateTestUser:url];
        return YES;
    }
    return NO;
}

Return YES in the following method of the delegate in order to open URLs in your app:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {    
    // Return YES to open URL in your app
    return YES;
}

Add your URL Scheme and your URL Identifier in your app’s Info.plist file, as shown in the following image: