Contact Us

Installation

Pendo Help CenterInstallationiOS SDK Integration

iOS SDK Integration

warning: This article contains generic instructions. For personalized instructions for your Pendo instance, please use the instructions located within your App.

Overview

This SDK version was released on November 26, 2018.

Warning: To install this version, you will need to change your older Pendo Mobile installation code. The setVisitor and userAttributes API endpoints have changed in this update. You would also need to increment your app version.

Step 1. Install the SDK

Install the SDK using CocoaPods OR Manually:

CocoaPods

Open your Podfile and add the following lines:

platform:ios, '9.0'
use_frameworks!

# other pod statements

pod 'Insert', '~> 1.52.0.0'

Manually Install

  1. Download the latest 52 SDK framework from this link

  2. Unzip to extract the framework: InsertFramework.framework
  3. Copy InsertFramework.framework to your project’s Frameworks directory by dragging the framework to your project. When prompted, check the option to "Copy items if needed"
  4. Under Build Phases > Link Binaries With Libraries, verify that InsertFramework.framework is listed
  5. Under General > Embedded Binaries, press the + sign and add InsertFramework.framework
  6. Under General > Deployment Target verify that deployment target is set for 9.0 or later. Insert only supports iOS 9.0 or later

Step 2. Set a URL Scheme

  1. Under Info > URL Types, create a new URL by clicking the + button
  2. Set URL Schemes to Scheme ID
  3. Set Identifier to any name of your choosing

You can find your Scheme ID by following this Pendo Guide.

Step 3. Add Initialization Code

Use Objective-C OR Swift to add initialization code.

Using Objective-C

In your AppDelegate file add:

@import InsertFramework;

Add or modify the function openURL:

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options;
{
    if ([[url scheme] containsString:@"pendo"]) {
        [[InsertManager sharedManager] initWithUrl:url];
        return YES;
    }
    //  your code here ...
    return YES;
}

Under didFinishLaunchingWithOptions, add the following line of code:

(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    InsertInitParams *initParams = [[InsertInitParams alloc] init];
    [initParams setVisitorId:@"John Smith"];
    [initParams setVisitorData:@{@"Age":@27, @"Country":@"USA", @"Gender":@"Male"}];
    [initParams setAccountId:@"ACME"];
    [initParams setAccountData:@{@"Tier":@1, @"Timezone":@"EST", @"Size":@"Enterprise"}];

[[InsertManager sharedManager] initSDK:@"CHANGE TO YOUR API KEY"
                           companyName: @"CHANGE TO YOUR COMPANY ID"
                           initParams: initParams]; // call initSDK with initParams as a third parameter

note: To find your API-Key and Company Id follow this Pendo Guide

The variables are defined as the following so you can update the code to your visitor parameters:

The above parameters should be swapped with your visitor/account identifiers as follows:

  • Visitor ID: a user identifier (e.g. John Smith)
  • Visitor Data: customized data about the visitor. Please note that this requires setup in Pendo UI. You may follow this Pendo Guide
  • Account ID: an affiliation of the user to a specific company or group (e.g. Acme Inc)
  • Account Data: customized data about the account

note: Passing NULL or not setting the initParams.visitorId to the visitorId will generate an anonymous visitor id .

To update the visitor/account IDs during the mobile session, use the following:

[[InsertManager sharedManager] switchVisitor:@"John Smith"
                               accountId:    @"ACME"
                               visitorData:  @{@"Age": @"27", @"Country":@"USA",@"Gender":@"Male"}
                               accountData:  @{@"Tier":@1, @"Timezone":@"EST", @"Size":@"Enterprise"}];

This code acts as similar to the initSDK function. It will end the old session and create a new one to retrieve all guides based on the new information.

Using Swift

Add a bridging header as described in this Apple documentation.

Add the following import statement to the bridging header:

@import InsertFramework;

In your AppDelegate file add:

    import InsertFramework.InsertManager

Add or modify the function:

func application(_ app: UIApplication,
 open url: URL,
 options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool
    {
        if url.scheme?.range(of: "insert") != nil {
            InsertManager.shared().initWith(url)

            return true
        }
        // your code here...
        return true
    }

Under the function didFinishLaunchingWithOptions add the following line of code:

let initParams = InsertInitParams()
initParams.visitorId = "John Smith"
initParams.visitorData = "["Age": "27", "Country": "USA", "Gender": "Male"]"
initParams.accountId = "Acme"
initParams.accountData = "["Tier": "1", "Timezone": "EST", "Size": "Enterprise"]"

InsertManager.shared().initSDK(
            "CHANGE THIS TO YOUR API KEY",
            companyName:"CHANGE THIS TO YOUR COMPANY ID",
            initParams: initParams) // call initSDK with initParams as a third parameter.

note: To find your API-Key and Company Id follow this Pendo Guide

The variables are defined as the following so you can update the code to your visitor parameters:

The above parameters should be swapped with your visitor/account identifiers as follows:

  • Visitor ID: a user identifier (e.g. John Smith)
  • Visitor Data: customized data about the visitor. Please note that this requires setup in Pendo UI. You may follow this Pendo Guide
  • Account ID: an affiliation of the user to a specific company or group (e.g. Acme Inc)
  • Account Data: customized data about the account

note: Passing NULL or not setting the initParams.visitorId to the visitorId will generate an anonymous visitor id .

To update the visitor/account IDs during the mobile session, use the following:

InsertManager.shared().switchVisitor("John Smith", accountId: "ACME", visitorData: "["Age": "27", "Country": "USA", "Gender": "Male"]", accountData: "["Tier": "1", "Timezone": "EST", "Size": "Enterprise");

This code acts as similar to the initSDK function. It will end the old session and create a new one to retrieve all guides based on the new information.

Test your changes

  • Test using Xcode: Run the app while attached to Xcode. Review the device log and look for the following message:
    • Pendo Mobile SDK was successfully integrated and connected to the server. App version identified: ‘X.Y.Z’.
  • Test using the Pendo UI:

(Optional) Custom Events

With mobile Custom Events you can programmatically send events from your code to Pendo. These events can be used to immediately trigger a guide, guide segmentation and analytics. To use custom events in Pendo, you first need to define the events in the Pendo console (follow this Pendo Guide) and then place the generated snippet in your app to trigger the event.

For Swift you may use:

var params: Dictionary<String, String> = Dictionary();
InsertManager.sharedManager().eventOccurred("EVENT_NAME_HERE", params:params);

(Optional) Push notification support

Pendo provides support for push notification. In order to enable Pendo push-notification in your App, you must call an API on the Insert SDK to set the unique push. For further information on how to achieve that see our documentation.

Upgrading to newer minor SDK updates

To refresh your Pendo SDK perform the following steps:

  • If using pod files, replace the reference to insert SDK with the new version described above. Then run ‘pod repo update’
  • If you have manually downloaded the insert SDK. Replace the insert SDK with the new version provided above
  • Insert is "version aware". To be able to distinguish the old SDK from the new, you must increment the version of your app
  • Review the release notes for any backward compatibility issues
© 2019 Pendo  |  Terms of Service  |  Privacy Policy