Quickstart - Objective-C¶

Compatibility

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

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, '8.0'
target 'Your-target-name' do
    pod 'PulseSDK', :git => 'https://bitbucket.org/pulseid/pulse-ios-release.git', :tag => "3.3"
end

Manual Install

Install the SDK by adding the PulseSDK.framework file to the project under Embedded Binaries. The PulseSDK.framework file is located in the Pods repository.

Embedded Binaries

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 Execution

Enable Bluetooth LE options under Project Capabilities:

Quickstart Capabilities

Import SDK¶

Import PulseSDK module in the projectname-Bridging-Header.h file.

User Opt-in

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

Background Execution

Enable Location updates and Bluetooth LE options under Project Capabilities:

Quickstart Capabilities

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

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:

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 want to permission prompt as soon as the SDK starts, consider customising the workflow:

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

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 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.

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

In this mode, in didFinishLaunchingWithOptions, the method startMonitoringStartSdk has two YES parameters.

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().startMonitoring()
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunched(onNotificationClick: notification, startInForeground: true, background: true)

        }
        else{
            PulseSDK.sharedClient().startMonitoring()
        }
    }

    return true
}

To interact in foreground and background modes:

In this mode, in didFinishLaunchingWithOptions, the method startMonitoringStartSdk has foreground parameter YES and background parameter NO.
In applicationDidEnterBackground, the method startSdk has two YES parameters.

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)
        PulseSDK.sharedClient().startMonitoring()
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunched(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 this mode, in didFinishLaunchingWithOptions, the method startMonitoringStartSdk has two YES parameters.
In applicationDidEnterBackground, the method startSdk has foreground parameter YES background parameter 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
        PulseSDK.sharedClient().startMonitoring()
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{
            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunched(onNotificationClick: notification, startInForeground: true, background: true)
        }
        else{{
            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 method startMonitoringStartSdk has foreground parameter YES background parameter 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
        PulseSDK.sharedClient().setForegroundMode(true, backgroundMode: false)
        PulseSDK.sharedClient().startMonitoring()
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{
            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunched(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 method startMonitoringStartSdk has foreground parameter NO background parameter 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)
        PulseSDK.sharedClient().startMonitoring()
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunched(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

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

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

UINotification

func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
    PulseSDK.sharedClient().loadView(onNotificationClick: notification, startSdkForeground: true, startSdkBackground: 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()

After stopping, to restart the PulseSDK Service:

    PulseSDK.sharedClient().enable()