IOS Developer API Documentation

Last Updated:

Overview

This document describes the Pendo iOS SDK Public APIs. 

Pendo Class Public API - SDK Version 2.10+

Return type

Public API method - Swift

Public API method - Objective-C

Description

static PendoManager

shared()

sharedManager

Returns a shared instance of the PendoManager.

Void

setup(appKey: String)

setup:(NSString *_Nonnull appkey)

Initializes the Pendo SDK. Call this API in didFinishLaunchingWithOptions.

This API should be used instead of initSDK and initSDKWithoutVisitor that will be deprecated in future versions. 

Void

startSession(visitorId: String?, accountId: String?, visitorData: [String: Any]?, accountData:  [String: Any]?)

startSession:(NSString *_Nullable)visitorId accountId:(NSString *_Nullable)accountId visitorData:(NSDictionary *_Nullable)visitorData accountData:(NSDictionary *_Nullable)accountData 

Starts mobile session with provided visitor and account information. If a session is already in progress, the session will end and a new session will start.

To generate an anonymous visitor, pass nil as the  visitorId.

This API should be used instead of switchVisitor that will be deprecated in future versions. 

Must be called after the SDK was initialized.

Void

endSession()

endSession

Ends the active session and stops collecting analytics or show guides to the user. More details here.

Must be called after the SDK was initialized.

Void

clearVisitor()

clearVisitor

Ends the active session starts a new session with an anonymous visitor.

Must be called after the SDK was initialized.
This API is deprecated as of SDK version 2.15.0. Please use startSession API with all arguments set to nil instead.

Void

setVisitorData(visitorData: [String: Any])

setVisitorData:(NSDictionary *_Nonnull)visitorData 

Update the visitor metadata. 

Must be called after the SDK was initialized.

Void

setAccountData(accountData: [String: Any])

setAccountData:(NSDictionary *_Nonnull)accountData 

Update the account metadata

Must be called after the SDK was initialized.

String (get)

visitorId

visitorId

Property: Returns the ID of the visitor in the active session. 

 

String (get)

accountId

accountId

 

Property: Returns the ID for the account in the active session. 

 

Void (set)

accountId

accountId

Property: Sets the ID for the account in the active session. 

This API is deprecated as of SDK version 2.15.0. Please use startSession API with the desired accountId.

Void

track(event: String, properties: [String: Any]?)

track:(NSString *_Nonnull)event properties:(NSDictionary *_Nullable)properties

Sends a track event with the specified properties.

Must be called after the SDK was initialized.

Void

dismissVisibleGuides()

dismissVisibleGuides

Dismisses all visible guide.

Void

pauseGuides(dismissGuides: Bool)

pauseGuides:(BOOL)dismissGuides

Pauses any guides from showing during an active session. If dismissGuides is TRUE then all visible guides will be dismissed.

Must be called after the SDK was initialized.

Void

resumeGuides()

resumeGuides

Resumes showing guides during the active session. Should only be used after pauseGuides. 

Must be called after the SDK was initialized.

String

getDeviceId()

getDeviceId

Returns the device's unique Pendo-generated id. The device id is used by Pendo to generate a unique id for each anonymous visitor. This id is unique per application.

 

Void

enableClickAnalytics(view: id)

(void)enableClickAnalytics:(id)view;

This method makes the object passed in act as a taggable/clickable object by Pendo SDK. The object will no longer be treated as taggable/clickable object once its not visible on screen

param view passed in object, should be of type UIVIew. API should be added in viewDidLoad
return void

Void

 

setDebugMode(isDebugEnabled: Bool

 

setDebugMode:(BOOL)isDebugEnabled

Use when you want to enable/disable debug log from Pendo SDK.


Pendo Class Public API For JWT - SDK Version 2.13+

Return type

Public API method - Swift

Public API method - Objective-C

Description

Void

startSession(jwt: String, signingKeyName: String)

startSession:(NSString *_Nonnull)jwt signingKeyName:(NSString *_Nonnull)signingKeyName 

Starts a mobile session with the provided JWT and the key name used to sign the JWT. The JWT containing the visitor and account information should be created and signed using the key on your server-side. Call this API with the JWT and name of the signing key after obtaining the information from your server-side. If a session is already in progress, the session will end and a new session will start.

To generate an anonymous visitor, the payload must contain both a visitor and account elements with an empty string as their id.

This API can only be used once the "use signing metadata" of your application flag is enabled. 

Must be called after the SDK was initialized.

Void

setVisitorData(jwt: String, signingKeyName: String)

setVisitorData:(NSString *_Nonnull)jwt signingKeyName:(NSString *_Nonnull)signingKeyName

Update the visitor metadata. The JWT containing the new / updated visitor information should be created and signed using the key on your server-side. Call this API with the JWT and name of the signing key after obtaining the information from your server-side. The JWT payload should not include account information and the visitor id must match the visitor id used to start the session.

This API can only be used once the "use signing metadata" of your application flag is enabled. 

Must be called after the SDK was initialized.

Void

setAccountData(jwt: String, signingKeyName: String)

setAccountData:(NSString *_Nonnull)jwt signingKeyName:(NSString *_Nonnull)signingKeyName

Update the account metadata. The JWT containing the new / updated account information should be created and signed using the key on your server-side. Call this API with the JWT and name of the signing key after obtaining the information from your server-side. The JWT payload should not include visitor information and the account id must match the account id used to start the session.

This API can only be used once the "use signing metadata" of your application flag is enabled. 

Must be called after the SDK was initialized.


Pendo Class Public APIs - SDK Version 2.9 and lower 

Return type

Public API method

-Swift

Public API method 

Objective-C

Description

Void

initSDK(appKey: String, initParams: PendoInitParams?)

initSDK:(NSString *_Nonnull)appKey initParams:(PendoInitParams *_Nullable)initParams

Initializes the Pendo SDK using the specified app key and params.

Void

initSDKWithoutVisitor(appKey: String)

initSDKWithoutVisitor:(NSString *_Nonnull)appKey

Initializes the Pendo SDK without visitor and account data, using the specified app key.

Void

switchVisitor(visitorId: String?, accountId: String?, visitorData: [String: Any]?, accountData:  [String: Any]?)

switchVisitor:(NSString *_Nullable)visitorId accountId:(NSString *_Nullable)accountId visitorData:(NSDictionary *_Nullable)visitorData accountData:(NSDictionary *_Nullable)accountData 

Ends the current session when there is an active session then starts a new session with the new visitor and account information. 

Passing nil as the visitorId will generate an anonymous visitor id. 

Must be called after the SDK was initialized.

Pendo Class: PendoInitParams

The following class is used in InitSDK() methods. It includes details about the visitor and the account that can later be used for segmentation and analysis within Pendo.

Make sure to send to Pendo only user and account details that are allowed by your security team and that are not considered private information. Pendo will not share these details with any 3rd party.

Return type

Public API method - Swift

Public API method - Objective-C

Description

PendoInitParams

PendoInitParams()

[[PendoInitParams alloc] init]

Constructor

 

Property Type

Public Property Name

Description

String (set)

visitorId

Sets the Visitor ID for the session that will start following the initialization with this PendoInitParams object.

Nil value is used for anonymous visitor

Dictionary<String, NSObject> (set)

visitorData

Sets the Visitor metadata for the session that will start following the initialization with this PendoInitParams object.

String (set)

accountId

Sets the Account ID for the session that will start following the initialization with this PendoInitParams object. 

Dictionary<String, NSObject> (set)

accountData

Sets the account's metadata for the session that will start following the initialization with this PendoInitParams object.

Pendo Initialization Guidelines

  1. setupshould only be called once during the application lifecycle.
  2. startSessionmay take time to complete, depending on network connectivity. NSNotificationCenter should be used to receive notifications when Pendo SDK initialization completes. 
  3. startSession is used to set a visitorID and/or AccountID. No action will be taken if Visitor and Account ID did not change. 
  4. endSession should be used to end the visitor session when the user logs out of the application. 

SDK Initialization 

setupshould be placed in the AppDelegate  application(_:didFinishLaunchingWithOptions:) 

Setup the SDK 

Objective-C

@import Pendo;

In the applicationapplication(_:didFinishLaunchingWithOptions:) method, add the following code:

 

Objective-C

NSString * appKey = @"YOUR_API_KEY";
[[PendoManager sharedManager] setup: appKey];

Swift

let appKey = "YOUR_API_KEY"
PendoManager.shared().setup(appKey)

 

Start mobile session

When you would like to start the session with a visitor (identified or anonymous) call startSession. To generate an anonymous visitor, pass nil as the  visitorId.

Objective-C

@import Pendo;

Add the following code to your application where your visitor is known: 

Identified Visitor 

Objective-C

NSString * visitorId = @"John Smith";
NSString * accountID = @"Acme Inc";

//set visitor metadata
NSDictionary * visitoraData = @{@"Age":@27, @"Country":@"USA", @"Gender":@"Male"};

//set account metadata
NSDictionary * accountData = @{@"Tier":@1, @"Size":@"Enterprise"};

Swift

let visitorId = "John Smith"
let accountID = "Acme Inc"

//set visitor metadata
let visitoraData = ["Age": "27", "Country": "USA", "Gender": "Male"]

//set account metadata
let accountData = ["Tier": "1", "Timezone": "EST", "Size": "Enterprise"]

Anonymous Visitor:

Objective-C

NSString * visitorId = nil;
NSString * accountID = nil;
NSDictionary * visitoraData = nil;
NSDictionary * accountData = nil;

Swift

let visitorId = nil
let accountId = nil
let visitoraData = nil
let accountData = nil

Call startSession() method - This code will start the mobile session and retrieve all guides based on the provided information.

Objective-C

[[PendoManager sharedManager] startSession: visitorId
accountId: accountId
visitorData: visitorData
accountData: accountData];

Swift

PendoManager.shared().startSession(visitorId, 
accountId: accountId,
visitorData: visitorData,
accountData: accountData)

Track Events Flow

This method allows you to pass track event information using the Pendo SDK. 

Use Case Example:  Since Pendo already tracks click events (RAClick events) and screen changes (RAScreenView events), a good example would be a callback you would like to track (i.e. transaction response callbacks, such as payment completed or failed, etc.).

Objective-C

NSDictionary *eventProperties = @{@"propety1":@"value1", @"propety2":@"value2"};
[[PendoManager sharedManager] track:@"customEvent1" properties:eventProperties];

Swift

let eventProperties = ["propety1": "value1", "propety2": "value2"]
PendoManager.shared().track("customEvent1", eventProperties)

 

NSNotificationCenter 

  • You can register to Pendo notifications to be notified on Pendo's initialization progress.
  • Using notifications can affect your user journey and the timing of guide display with Pendo - in case you want to make sure that Pendo processed all guides by the time the user starts using the app, you can show the app's UI only after kPNDDidSuccessfullyInitializeSDKNotification . At that time, all mobile guides are processed and ready to be displayed to your users.

Notification Key Name

Usage

kPNDDidSuccessfullyInitializeSDKNotification

Receive a notification when SDK initialization successfully completed.

kPNDErrorInitializeSDKNotification

Receive a notification when SDK initialization failed.