Skip to content

Quickstart

Compatibility

The Pulse library works with iOS 12.0 onwards with devices equipped with Bluetooth 4.0 or higher.

Integration Example

Please use the Demo Application as a reference implementation for the SDK.

Installation

Add Pulse SDK

You can install the Pulse SDK either using Pod or manually linking the framework into your project.

Pod Install

Put the following text in your Pod.file.

platform :ios, '12.0'
target 'Your-target-name' do
    use_frameworks!
    pod 'PulseSDK/Core', :git => 'https://bitbucket.org/pulseid/pulse-ios-release.git', :tag => "3.12.0"
end

Manual Install

If you are unable to install via CocoaPods, we provide dynamic frameworks including PulseSDK's dependencies.

Please follow the steps to integrate PulseSDK:

  • Clone the repository: manual integration demo
  • Add the followings frameworks under Framework folder as embedded binaries in your Xcode project

Quickstart Capabilities

Add permissions

Location permissions

For handling permission of location services, add the following keys and explanation in your Info.plist

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your explanation for using  user's location goes here</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Your explanation for using  user's location goes here</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your explanation for using  user's location goes here</string>

User Opt-in

Its is important that you clearly and effectively communicate the reason for using the User's location using above settings.

Background Modes

The core functionality in SDK does not require Background Modes.

If you are using Smaller Geofence, please refers to settings in Smaller Geofence

Import SDK


// Import PulseCore module in the `AppDelegate.h` file.
@import PulseCore;

// Import PulseCore module in the `projectname-Bridging-Header.h` file.
@import PulseCore;

If you are using UserNotifications in iOS 10, also import the following code in AppDelegate file:


@import UserNotifications;
@interface AppDelegate : UIResponder <UIApplicationDelegate,UNUserNotificationCenterDelegate>
@property (strong, nonatomic) UNUserNotificationCenter *center;

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate

Integration Example

Please use the Demo Application as a reference implementation for the SDK.

Configuration

App-key and end-point

To initialize the SDK use the setConfig method with your app key within the didFinishLaunchingWithOptions method in the AppDelegate.m file:


//key will be provided by Pulse
NSDictionary* config=@{@"url":@"your-endpoint-url",@"key":@"your-app-key-here"};
[[PulseSDK sharedClient] setConfig:config];

let config: [String: String] = ["url":"your-endpoint-url", "key":"your-app-key-here"]
PulseSDK.sharedClient().setConfig(config)

Seek permissions

The user will be prompted by iOS to provide permission to app for sharing their location. This prompt will appear when the SDK starts for the first time.

If you do not want to prompt for permission as soon as the SDK starts, customise the workflow:

  1. Add new entry "permission":"custom" in config.


NSDictionary* config=@{@"url":@"your-endpoint-url",@"key":@"your-app-key-here", @"permission":@"custom"};

let config: [String: String] = ["url":"your-endpoint-url","key":"your-app-key-here", "permission":"custom"]
  1. Call the permission request when you need it in your workflow


[[PulseSDK sharedClient] requestForLocationPermission];
[[PulseSDK sharedClient] requestForNotificationPermission];

PulseSDK.sharedClient().requestForLocationPermission()
PulseSDK.sharedClient().requestForNotificationPermission()

Integration

Set Session

By default, the SDK will generate a 32 char hexadecimal session id, based on app's APP VENDOR IDENTIFIER. All analytics and data will be gathered against this session id

Use the setSessionID method before starting the service, if you want to use a custom identifier. This method must be called after setConfig method and before initialising the service. Use the getSessionId method to obtain the current session identifier.


[[PulseSDK sharedClient] setSessionId:@"your-session-id"];

PulseSDK.sharedClient().setSessionId("your-session-id")

Start Services

Pulse interactions can be triggered even when the app is in the background or inactive (not in memory). Based on project requirements, Pulse's service can be started in different modes to selectively trigger interactions:

To interact in all modes (foreground, background, and terminated) modes

  • By default, SDK interacts in all modes.
  • In didFinishLaunchingWithOptions, the method loadViewOnNotificationClick has foreground parameter YES background parameter YES.


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //key and url will be provided by Pulse
    NSDictionary* config = @{@"url":@"your-endpoint-url",@"key":@"your-app-key-here"};
    [[PulseSDK sharedClient] setConfig:config];

    if (@available(iOS 10, *)) {
            self.center=[UNUserNotificationCenter currentNotificationCenter];
            self.center.delegate = self;
    }
    else{
            if ([launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey]) {                    
                UILocalNotification* notification = [launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey];
                [[PulseSDK sharedClient] loadViewOnNotificationClick:notification startInForeground:YES background:YES];
            }
    }
    [[PulseSDK sharedClient] startMonitoring];

    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    let config: [String: String] = ["url":"your-endpoint-url","key":"your-app-key-here"]

    PulseSDK.sharedClient().setConfig(config)

    if #available(iOS 10, *) {
        let center = UNUserNotificationCenter.current()
        center.delegate = self
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{
            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification
            PulseSDK.sharedClient().loadView(onNotificationClick: notification, startInForeground: true, background: true)
        }
    }
    PulseSDK.sharedClient().startMonitoring()

    return true
}

To interact in foreground and background modes:

  • In this mode, in didFinishLaunchingWithOptions, the methods setForegroundMode & loadViewOnNotificationClick have foreground parameters YES background parameters NO.
  • In applicationDidEnterBackground, the method setForegroundMode has two YES parameters.


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //key and url will be provided by Pulse
    NSDictionary* config=@{@"url":@"your-endpoint-url",@"key":@"your-app-key-here"};
    [[PulseSDK sharedClient] setConfig:config];

    if (@available(iOS 10, *)) {
            self.center=[UNUserNotificationCenter currentNotificationCenter];
            self.center.delegate = self;
            [[PulseSDK sharedClient] setForegroundMode:YES backgroundMode:NO];
    }
    else{
            if ([launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey]) {                    
                UILocalNotification* notification=[launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey];
                [[PulseSDK sharedClient]loadViewOnNotificationClick:notification startInForeground:YES background:NO];
            }
            else{
                [[PulseSDK sharedClient] setForegroundMode:YES backgroundMode:NO];
            }
    }
    [[PulseSDK sharedClient] startMonitoring];

    return YES;
}
- (void)applicationDidEnterBackground:(UIApplication *)application{
    [[PulseSDK sharedClient] setForegroundMode:YES backgroundMode:YES];
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    let config: [String: String] = ["url":"your-endpoint-url","key":"your-app-key-here"]

    PulseSDK.sharedClient().setConfig(config)

    if #available(iOS 10, *) {
        let center = UNUserNotificationCenter.current()
        center.delegate = self
        PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: false)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().loadView(onNotificationClick: notification, startInForeground: true, background: false)
        }
        else{
            PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: false)
        }
    }
    PulseSDK.sharedClient().startMonitoring()

    return true
}
func applicationDidEnterBackground(_ application: UIApplication) {
    PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: true)
}

** To interact in foreground and terminated modes:**

  • In didFinishLaunchingWithOptions, the method loadViewOnNotificationClick has foreground parameter YES background parameter YES

  • In applicationDidEnterBackground, the method setForegroundMode has foreground parameter YES background parameter NO.


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //key and url will be provided by Pulse
    NSDictionary* config=@{@"url":@"your-endpoint-url",@"key":@"your-app-key-here"};
    [[PulseSDK sharedClient] setConfig:config];

    if (@available(iOS 10, *)) {
            self.center=[UNUserNotificationCenter currentNotificationCenter];
            self.center.delegate = self;
    }
    else{
            if ([launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey]) {                    
                UILocalNotification* notification=[launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey];
                [[PulseSDK sharedClient]loadViewOnNotificationClick:notification startInForeground:YES background:YES];
            }
    }

    [[PulseSDK sharedClient] startMonitoring];

    return YES;
}
- (void)applicationDidEnterBackground:(UIApplication *)application{
    [[PulseSDK sharedClient] setForegroundMode:YES backgroundMode:NO];
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    let config: [String: String] = ["url":"your-endpoint-url","key":"your-app-key-here"]

    PulseSDK.sharedClient().setConfig(config)

    if #available(iOS 10, *) {
        let center = UNUserNotificationCenter.current()
        center.delegate = self
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{
            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().loadView(onNotificationClick: notification, startInForeground: true, background: true)
        }
    }

    PulseSDK.sharedClient().startMonitoring()

    return true
}
func applicationDidEnterBackground(_ application: UIApplication) {
    PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: false)
}

** To run in foreground mode only:**

  • In this mode, in didFinishLaunchingWithOptions, the methods setForegroundMode & loadViewOnNotificationClick have foreground parameters YES background parameters NO.


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //key and url will be provided by Pulse
    NSDictionary* config=@{@"url":@"your-endpoint-url",@"key":@"your-app-key-here"};
    [[PulseSDK sharedClient] setConfig:config];

    if (@available(iOS 10, *)) {
            self.center=[UNUserNotificationCenter currentNotificationCenter];
            self.center.delegate = self;
            [[PulseSDK sharedClient] setForegroundMode:YES backgroundMode:NO];       
    }
    else{
            if ([launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey]) {                    
                UILocalNotification* notification=[launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey];
                [[PulseSDK sharedClient] loadViewOnNotificationClick:notification startInForeground:YES background:NO];
            }
            else{
                [[PulseSDK sharedClient] setForegroundMode:YES backgroundMode:NO];
            }
    }

    [[PulseSDK sharedClient] startMonitoring]; 

    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    let config: [String: String] = ["url":"your-endpoint-url","key":"your-app-key-here"]

    PulseSDK.sharedClient().setConfig(config)

    if #available(iOS 10, *) {
        let center = UNUserNotificationCenter.current()
        center.delegate = self
        PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: false)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{
            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().loadView(onNotificationClick: notification, startInForeground: true, background: false)
        }
        else{
            PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: false)
        }
    }

    PulseSDK.sharedClient().startMonitoring()

    return true
}

** To run in background and terminated mode:**

  • In this mode, in didFinishLaunchingWithOptions, the methods setForegroundMode & loadViewOnNotificationClick have foreground parameters NO background parameters YES.


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //key and url will be provided by Pulse
    NSDictionary* config=@{@"url":@"your-endpoint-url",@"key":@"your-app-key-here"};
    [[PulseSDK sharedClient] setConfig:config];

    if (@available(iOS 10, *)) {
            self.center=[UNUserNotificationCenter currentNotificationCenter];
            self.center.delegate = self;
            [[PulseSDK sharedClient] setForegroundMode:NO backgroundMode:YES];
    }
    else{
            if ([launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey]) {                    
                UILocalNotification* notification=[launchOptions valueForKey:UIApplicationLaunchOptionsLocalNotificationKey];
                [[PulseSDK sharedClient] loadViewOnNotificationClick:notification startInForeground:NO background:YES];
            }
            else{
                [[PulseSDK sharedClient] setForegroundMode:NO backgroundMode:YES];
            }
    }

    [[PulseSDK sharedClient] startMonitoring];

    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

    let config: [String: String] = ["url":"your-endpoint-url","key":"your-app-key-here"]

    PulseSDK.sharedClient().setConfig(config)

    if #available(iOS 10, *) {
        let center = UNUserNotificationCenter.current()
        center.delegate = self
        PulseSDK.sharedClient().setForegroundMode(false, backgroundMode: true)

    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().loadView(onNotificationClick: notification, startInForeground: false, background: true)
        }
        else{
            PulseSDK.sharedClient().setForegroundMode(false, backgroundMode: true)
        }
    }

    PulseSDK.sharedClient().startMonitoring()

    return true
}

Receive notifications

In order to show notifications from Pulse Platform, you will need to implement delegate methods.

From iOS 10 and above, we support the delegate of UNNotificationCenter.

UserNotification


-(void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)(void))completionHandler {
    //app was in background and user clicked on local alert notification to bring app in foreground
    [[PulseSDK sharedClient] loadViewOnUNNotificationClick:response.notification startInForeground:YES background:YES];
}

-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler{
    //app was in foreground
    [[PulseSDK sharedClient] loadViewOnUNNotificationClick:notification startInForeground:YES background:YES];
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    PulseSDK.sharedClient().loadView(onUNNotificationClick: response.notification, startInForeground: true, background: true)
}
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    PulseSDK.sharedClient().loadView(onUNNotificationClick: notification, startInForeground: true, background: true)
}

For devices below iOS 10, we support delegate of UINotification.

UINotification


-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification{
    //app was in background and user clicked on local alert notification to bring app in foreground
    [[PulseSDK sharedClient] loadViewOnNotificationClick:notification startInForeground:YES background:YES];
}

func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
    PulseSDK.sharedClient().loadView(onNotificationClick: notification, startInForeground: true, background: true)
}

Stop Services

Pulse interactions can be force stopped if required. This feature can be used to implement custom user controls within the app to allow users to opt-in/out of using Pulse-powered features.

  • To stop the PulseSDK Service:


[[PulseSDK sharedClient] disable];

PulseSDK.sharedClient().disable()
  • To restart the PulseSDK Service:

Immediate Start

After enabling the SDK, SDK will start after relaunching an App. If you wish to make SDK running immediately, please add the startMonitoring method.


[[PulseSDK sharedClient] enable];
// To immediately start the SDK without relaunching an App.
[[PulseSDK sharedClient] startMonitoring]; 

PulseSDK.sharedClient().enable()
// To immediately start the SDK without relaunching an App.
PulseSDK.sharedClient().startMonitoring();