iOS SDK Integration

Please read this document to get started: getting started with InsightIQ.

Overview

Connect SDK is a quick and secure way to connect work platforms in your iOS apps. Connect SDK manages work platform authentication (credential validation, multi-factor authentication, error handling, etc).

To start integration with the SDK, clone the GitHub repository. It has a sample application, which provides a reference implementation.

Requirements

To get started, you will require a client ID and secret to access the environment. To get your API credentials, please register on our dashboard. APIs must be called only from your server and never from your app / frontend as this is a security issue.

Please note that our SDK needs a minimum iOS version 12 to work. In other words, we only support iOS version 12 and above.

Integration

1. Add the Connect SDK to your app

If you haven’t aleady, install the latest version of CocoaPods. Refer the official CocoaPods documentation here if you want to know more about how to integrate CocoaPods with your project.
Once you have a Podfile, add the following to it:

platform :ios, '12.0'

target '<YourApp>' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  # Pods for <YourApp>
  pod 'PhylloConnect'

end

Run the following command from a terminal (the same command works for updates too!):

pod install --repo-update

The current SDK version is 0.3.2.

2. Initialize the Connect SDK

Before you initialize SDK, you need to first create an SDK token. The token can be configured to customize Connect SDK flow. To see how to create a new SDK token, see the API reference for create an SDK token API. This token is valid for precisely one week from the time of creation.

3. Create a Connect SDK Configuration

Each time you start the SDK, you will need to initialize the SDK with the token and a few other parameters.

import PhylloConnect

...

  var phylloConfig = [String:Any]()
  phylloConfig["clientDisplayName"] = clientDisplayName  // the name of your app that you want the creators to see while granting access
  phylloConfig["environment"] = environment  // the mode in which you want to use the SDK,  `staging` or `production`
  phylloConfig["userId"] = userId  // the unique user_id parameter returned by the API when you create a user (see https://docs.insightiq.ai/docs/api-reference/reference/openapi.v1.yml/paths/~1v1~1users/post)
  phylloConfig["token"] = token
  phylloConfig["singleAccount"] = singleAccount  // (optional) set this to true if you want the creator to be able to connect only one account, this is `false` by default
  phylloConfig["workPlatformId"] = workPlatformId  // (optional) the unique work_platform_id of a specific work platform, if you want the creator to skip the platform selection screen and just be able to connect just with a single work platform
  phylloConfig["delegate"] = self  // delegate object that will receive the SDK events, read further for listening to events

  PhylloConnect.shared.initialize(config: phylloConfig)

...

Table below lists the options accepted by the config.

Name	Description	Data type	Mandatory
clientDisplayName	The name you want to show the users while using the Connect SDK.	String	Yes
environment	The Phyllo environment - staging or production - which you want to connect to.	Enum	Yes
userId	Phyllo `userID` of the user whose account is about to be connected.	String	Yes
token	Token generated by the create an SDK token API.	String	Yes
singleAccount	This can be set to `true` if you want the creator to be able to connect only one account (default is `false`).	Boolean	No
workPlatformId	Work platform ID (can be fetched from retrieve all work platforms API) of the platform if you want the user to skip the platform selection screen and be restricted to a single pre-decided platform.	String	No
delegate	Reference to an object implementing the PhylloConnectDelegate, which contains event listeners for Connect SDK events.	instance of PhylloConnectDelegate	Yes

4. Listen for events

You need to listen for events in your app. These event triggers are listed below.

Event	Trigger	Method name
Account connected	Triggered when the user successfully connects a work platform account	onAccountConnected
Account disconnected	Triggered when the user successfully disconnects a work platform account	onAccountDisconnected
Token expired	Triggered when the `token` used to initialize the SDK is more than 7 days old	onTokenExpired
Exit	Triggered when the user exits the SDK	onExit
Connection failure (optional)	Triggered when the user has attempted connecting to the work platform but resulted in a failure	onConnectionFailure

Here is how you can do this for your iOS app.

Subscribe to the delegate methods in the class whose object you have set as delegate in the config.

extension YourDelegateClass : PhylloConnectDelegate {

    func onAccountConnected(account_id: String, work_platform_id: String, user_id: String) {  // gives the successfully connected account ID and work platform ID for the given user ID
        print("onAccountConnected => account_id : \(account_id),work_platform_id : \(work_platform_id),user_id : \(user_id)")
    }

    func onAccountDisconnected(account_id: String, work_platform_id: String, user_id: String) {  // gives the successfully disconnected account ID and work platform ID for the given user ID
        print("onAccountDisconnected => account_id : \(account_id),work_platform_id : \(work_platform_id),user_id : \(user_id)")
    }

    func onTokenExpired(user_id: String) {  // gives the user ID for which the token has expired
        print("onTokenExpired => user_id : \(user_id)")  // the SDK closes automatically in case the token has expired, and you need to handle this by showing an appropriate UI and messaging to the users
    }

    func onExit(reason: String, user_id: String) {  // indicates that the user with given user ID has closed the SDK and gives an appropriate reason for it
        print("onExit => reason : \(reason),user_id : \(user_id)")
    }

    func onConnectionFailure(reason: String, work_platform_id: String, user_id: String) {  // optional, indicates that the user with given user ID has attempted connecting to the work platform but resulted in a failure and gives an appropriate reason for it
        print("onConnectionFailure => reason : \(reason),work_platform_id : \(work_platform_id),user_id : \(user_id)")
    }
}

Here is a list of reasons with description, that you can receive in the onExit event.

`reason`	Description
BACK_PRESSED	User has pressed the back button. This can happen before or after a connection.
DONE_CLICKED	User has pressed the "DONE" button in the SDK. This usually happens after a successful connection.
EXIT_FROM_PLATFORM_SELECTION	User has pressed the cross button ("x") on the top right of the SDK from the screen where they have to select a platform. This can happen before or after a connection.
EXIT_FROM_PLATFORM_{name of the work platform}	User has pressed the cross button ("x") on the top right of the SDK from the screen where they are shown details about connecting to a platform (after selecting the platform). This can happen before or after a connection.
EXIT_FROM_CONNECTION_FAILED	User has pressed the cross button ("x") on the top right of the SDK from the error screen where they are shown the error details about connecting to a certain work platform. This can happen after another successful connection to the same platform or another platform.

Here is a list of reasons with description, that you can receive in the onConnectionFailure event.

`reason`	Description
CONNECTION_ABANDONED	User has abandoned the account connection flow.
INCORRECT_ACCOUNT_TYPE	User has connected an incorrect account type.
INADEQUATE_PERMISSIONS	User has granted inadequate permissions.

5. Open the connection screen

After initialization, the Connect SDK flow can simply be invoked on any screen.

import PhylloConnect

...

  PhylloConnect.shared.open()

...

On successful account connection, you will also get notified via webhook to your server. Please read more about webhooks here and set them up accordingly.

Debug: check the SDK version

At any point, if you wish to ascertain the version of the SDK that is loaded in your app (for example, to debug), you can use the version method.

print(PhylloConnect.shared.version());

// console output
// {
//   "connect_ios_sdk_version": "<SemVer string>",
//   "min_supported_ios_version": "<iOS version string>",
//   "max_supported_ios_version": "<iOS version string>"
// }

Was this helpful?