Quickstart - Swift¶

Complete the steps described on this page, and in about five minutes you'll have integrated the Pulse SDK in your own application.

Set up your campaign first before you integrate the SDK in your application.

Installation¶

Follow this guide to install the SDK. You can either

install the SDK by linking the framework into your project folder
use Pods to install the SDK into your Xcode workspace.

Install the SDK manually

Install the SDK by adding the PulseSDK.framework file to the project under "Embedded Binaries"

Quickstart Embedded Binaries

Install the SDK through Pod

Put the following text in your Pod.file.

platform :ios, '8.0'
target 'Your-target-name' do
    pod 'PulseSDK', :git => 'https://pxidev@bitbucket.org/pxiiosteam/pulse-ios-sdk-pod.git', :tag => "3.0"
end

Replace the tag value with the latest repository version provided by Pulse.

Configure your Xcode project

For handling permission of location services, add the following code in your Info.plist

<key>NSLocationAlwaysUsageDescription</key>
<string>Your message goes here</string>

Import framework file in your projectname-Bridging-Header file.

For manual installation

#import <PulseSDK/PulseSDK.h>

Enable Bluetooth LE and Background fetch options under Project Capabilities:

Quickstart Capabilities

If you are using UserNotifications in iOS 10, import the protocol of UNUserNotificationCenterDelegate in the AppDelegate.swift file

class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate

Initialization

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

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

Notifications

In order to receive notifications, you will need to implement delegate methods. As iOS 10 has introduced UserNotification, our SDK can support the new delegate of UNNotificationCenter and the delegate of UINotification for devices not updated to iOS 10.

iOS 9

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

iOS 10

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

Running modes¶

The SDK can run under four different behaviours. In this section, you will learn how to configure them.

Running in 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().startMonitoringStartForeground(true, startInBackground: true)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunchedByClick(on: notification, startSdKForeground: true, startSdkBackground: true)

        }
        else{
            PulseSDK.sharedClient().startMonitoringStartForeground(true, startInBackground: true)
        }
    }

    return true
}

Running 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().startMonitoringStartForeground(true, startInBackground: false)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunchedByClick(on: notification, startSdKForeground: true, startSdkBackground: false)

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

Running 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().startMonitoringStartForeground(true, startInBackground: true)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunchedByClick(on: notification, startSdKForeground: true, startSdkBackground: true)

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

Running in Foreground mode.

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().startMonitoringStartForeground(true, startInBackground: false)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunchedByClick(on: notification, startSdKForeground: true, startSdkBackground: false)

        }
        else{
            PulseSDK.sharedClient().startMonitoringStartForeground(true, startInBackground: false)
        }
    }
    return true
}

Running 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().startMonitoringStartForeground(false, startInBackground: true)
    }
    else{
        if launchOptions?[UIApplicationLaunchOptionsKey.localNotification] != nil{

            let notification = launchOptions?[UIApplicationLaunchOptionsKey.localNotification] as! UILocalNotification!
            PulseSDK.sharedClient().appLaunchedByClick(on: notification, startSdKForeground: false, startSdkBackground: true)

        }
        else{
            PulseSDK.sharedClient().startMonitoringStartForeground(false, startInBackground: true)
        }
    }
    return true
}

Session ID¶

When the SDK is first installed, it will automatically create a session ID consisting of a 32 char hexadecimal string.

If you want to specify session ID, simply call setSessionId with your preferred session ID. This method will start a new session of the user on the Pulse platfrom.

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

To update session ID, simply call updateSessionId with your preferred session ID. This method will update the session ID of the user on the Pulse platform.

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

Geocode¶

The SDK provides a method to transform addresses into coordinates

PulseSDK.sharedClient().geocode(address: String!, completionHandler: ((CLLocationCoordinate2D, Error?) -> Void)!##((CLLocationCoordinate2D, Error?) -> Void)!##(CLLocationCoordinate2D, Error?) -> Void)

Calculate Distance¶

The SDK provides a method to calculate the distance between two CLLocation objects.

PulseSDK.sharedClient().getDistanceFrom(userLocation: CLLocation!, to: CLLocation!)