Install Gainsight PX SDK for iOS

Integrate Gainsight PX Editor

Gainsight PX Mobile Editor helps you manage PX engagements and Product Mapper from your mobile application. 

The In-app Editor allows you to:

• Preview engagements in the mobile app
• View the Product Tree
• Create, edit and delete Module/Features 
• Add Tap Rules for Module/Features

To use the in-app editor, copy the Scheme to integrate your mobile application with the your platforms that Gainsight supports.

You can activate the editor using deep linking and forwarding the link to the SDK. While forwarding the information, you as a developer have the ability to implement your own logic and permissions before launching the editor.

To integrate Gainsight PX with iOS:

1. Register for editor scheme in Info.plist as per the guidelines mentioned in 

https://developer.apple.com/documentation/xcode/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app

2. Perform `EnterEditing` in `openURL` method and also in `applicationContinueUserActivity` to support custom URL and deep linking as below:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : 
Any] = [:]) -> Bool {
          GainsightPX.shared.enterEditingMode(url: url)
          return true
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
         guard let incomingURL = userActivity.webpageURL else {
                 return false
         }
         GainsightPX.shared.enterEditingMode(url: incomingURL)
         return true
}                 
          

Initialize

With this option, Gainsight PX initializes either by using default configurations OR by setting up your product ID in <#APIKey#>. Also, you can modify some of the default configurations, so the Gainsight client works best for you.

import PXKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
let configurations = AnalyticsConfigurations(apiKey: <#APIKey#>)
GainsightPX.sharedInstance().initialise(configurations: configurations, completionBlock: <#GainsightPXErrorBlock?#> = nil)

return true

Create Events

Events help you to track data from your mobile application. Events are actions associated with your app. Events allow you to track various actions performed by a user on your app. Currently, the Gainsight PX SDK supports four types of events.

GainsightPX.sharedInstance().screen(title: <#String#>, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)
GainsightPX.sharedInstance().screen(title: <#String#>, properties: <#[String : Any]?#>, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)
GainsightPX.sharedInstance().screen(screen: <#ScreenEvent#>, properties: [String: Any]?, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)

GainsightPX.sharedInstance().identify(userId: <#String#>, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)

let user = User(userId: <#UserId#>)
GainsightPX.sharedInstance().identify(user: user, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)

let user = User.init(userId: <#String#>)
let account = Account.init(id: <#String#>)
GainsightPX.sharedInstance().identify(user: <#User#>, account: <#Account?#>, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)

user.customAttributes = <#[String: Any]#>
account.customAttributes = <#[String: Any]#>

GainsightPX.sharedInstance().custom(event: <#String#>, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)
GainsightPX.sharedInstance().custom(event: <#String#>, properties: <#[String : Any]?#>, errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)

General Method

There are three types of general methods:

• Flush
• Reset
• Enable/Disable

GainsightPX.sharedInstance().flush(errorCompletionBlock: <#GainsightPXErrorBlock?#> = nil)

GainsightPX.sharedInstance().reset()

 GainsightPX.shared.hardReset()

GainsightPX.shared.engagements(enable: Bool)

GainsightPX.disable() 

GainsightPX.shared.setSupportedInterfaceOrientations(orientation: UIInterfaceOrientationMask)

override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        GainsightPX.shared.setSupportedInterfaceOrientations(orientation: .landscapeRight)
        UIDevice.current.setValue(UIInterfaceOrientation.landscapeRight.rawValue, forKey: "orientation")
    }
    
    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        GainsightPX.shared.setSupportedInterfaceOrientations(orientation: .portrait)
        UIDevice.current.setValue(UIInterfaceOrientation.portrait.rawValue, forKey: "orientation")
    }

Set Global Context 

Once you create all the required events, you can set events with a global context. You can set a global context with key-value pairs and send it with the payload. Global context can be set on Date, String, Double, and Boolean data types. Global Context data is stored at the memory level and not disk-level. The key-value pairs are sent with the Payloads. If an application is terminated, all the key-value pairs are erased. 

Use the following code snippet to set globalContext:

let globalContext = GlobalContext();
globalContext.setDate(key: <#T##String#>, iso: <#T##String#>)
globalContext.setDate(key: <#T##String#>, value: <#T##Date#>)
globalContext.setDouble(key: <#T##String#>, value: <#T##Double#>)
globalContext.setString(key: <#T##String#>, value: <#T##String#>)
globalContext.setBoolean(key: <#T##String#>, value: <#T##Bool#>)
GainsightPX.sharedInstance().globalContext(context: globalContext)

Use the following code to set global context key, and remove the key pair value:

if globalContext.hasKey(key: "foo"){
  globalContext?.removeKeys(keys: ["foo"])
}

EngagementCallBack

Gainsight PX provides the Engagement Callback feature for mobile engagements that you create for mobile applications. This feature helps in receiving a callback for all button actions and URL clicks that the end-user performs on an engagement. Once you receive the callback, you can decide your next action like helping the user to navigate to a new screen, or perform an API call and so on.

Prerequisite

Ensure that you have installed/configured the Gainsight PX Mobile SDK v1.5.1 or above.

To use the Engagement Callback feature for iOS applications, you need to implement the EngagementCallback interface.
iOS PXEngagementCallBack has two variables: EngagementCallBackModel and Error. 

Add the EngagementCallback functionality as follows:

public typealias PXEngagementCallBack = (EngagementCallBackModel?, Error?) -> Bool
 
GainsightPX.shared.initialise(configurations: configurations,
                                          completionBlock: nil) { callback, error in
   ...
    return true
}

Error Handling

All exceptions occurred when creating events are passed into error callback GainsightPXErrorBlock. 

public typealias GainsightPXErrorBlock = (<#String#>, <#[String: Any]?#>, <#Error?#>) -> Void

The properties of GainsightPXErrorBlock are as follows:

• The first parameter informs about the invoked function name.
• The second parameter gives the event properties that were sent to create an event.
• The error parameter gives information about the exception that occurred.