Android 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 Android 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 Android version 21 to work. In other words, we only support Android SDK version 21 and above.
Integration
1. Add the Connect SDK to your app
In your project-level Gradle file
build.gradle, add rules to include the Maven Central repository.
buildscript {
repositories {
// Check that you have the following line (if not, add it):
google() // Google's Maven repository
mavenCentral() // Include to import Connect SDK dependencies
}
dependencies {
// ...
}
}In your module Gradle file (usually
app/build.gradle), add a line to the bottom of the file. The latest version of the SDK is usually uploaded to and can be found on Maven Central via their search feature.
android {
defaultConfig {
minSdkVersion 21 // or greater
}
// Enable Java 8 support for SDK to work
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
// ...
implementation "com.getphyllo:phyllo-connect:0.3.2"
}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.
var phylloConfig = hashMapOf<String, Any>(
clientDisplayName to clientDisplayName, // the name of your app that you want the creators to see while granting access
environment to PhylloConnect.ENVIRONMENT.STAGING, // the mode in which you want to use the SDK, `staging` or `production`
userId to 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)
token to token,
singleAccount to singleAccount, // (optional) set this to true if you want the creator to be able to connect only one account, this is `false` by default
workPlatformId to 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
callback to callback // callback object that will receive the SDK events, read further for listening to events
)
PhylloConnect.initialize(context = this@MainActivity,
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 environment - staging or production - which you want to connect to. | Enum | Yes |
userId |
| String | Yes |
token | Token generated by the create an SDK token API. | String | Yes |
singleAccount | This can be set to | 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 |
callback | Reference to an object implementing the ConnectCallback interface, which contains event listeners for Connect SDK events. | instance of ConnectCallback interface | Yes |
4. Listen for events
You can optionally 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 | 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 Android app.
Set the optional callback parameter in the initialize method. The value of this parameter is an object which is an instance of ConnectCallback interface, so your instance needs to implement the event methods.
var callback = object : ConnectCallback() {
override fun 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
Log.d(logTag, "onAccountConnected $account_id $work_platform_id $user_id")
}
override fun 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
Log.d(logTag, "onAccountDisconnected $account_id $work_platform_id $user_id")
}
override fun onTokenExpired(user_id: String?) { // gives the user ID for which the token has expired
Log.d(logTag, "onTokenExpired $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
}
override fun 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
Log.d(logTag, "onExit $reason $user_id")
}
override fun 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
Log.d(logTag, "onConnectionFailure $reason $work_platform_id $user_id")
}
}Here is a list of reasons with description, that you can receive in the onExit event.
| 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.
| 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.
PhylloConnect.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.version());
// console output
// {
// "connect_android_sdk_version": "<SemVer string>",
// "min_supported_android_version": "<android SDK version string>",
// "max_supported_android_version": "<android SDK version string>"
// }