Flutter SDK Integration

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

Overview

Connect SDK is a quick and secure way to connect work platforms in your Flutter-based mobile apps. The 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 and Android version 21 to work. In other words, we only support iOS version 12 and above, and Android SDK version 21 and above.

Integration

1. Add the Connect SDK to your app

To use this plugin, add phyllo_connect as a dependency in your pubspec.yaml file.

dependencies:
  flutter:
    sdk: flutter
  phyllo_connect: >=0.3.3

The current plugin version is 0.3.3.

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 'package:phyllo_connect/phyllo_connect.dart';

Map<String, dynamic> config = {
  'clientDisplayName': clientDisplayName,  // the name of your app that you want the creators to see while granting access
  'environment': PhylloEnvironment.staging.name,  // the mode in which you want to use the SDK,  `staging` or `production`
  '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)
  'token': token,
  '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
  '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
};
PhylloConnect.initialize(config);

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	`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

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 `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 Flutter app.

Set the handlers using the onConnectCallback method, which takes named handlers as input.

...
PhylloConnect.onConnectCallback(
  onAccountConnected: (account_id, work_platform_id, user_id) {  // gives the successfully connected account ID and work platform ID for the given user ID
    log('onAccountConnected: $account_id, $work_platform_id, $user_id');
  },
  onAccountDisconnected: (account_id, work_platform_id, user_id) {  // gives the successfully disconnected account ID and work platform ID for the given user ID
    log('onAccountDisconnected: $account_id, $work_platform_id, $user_id');
  },
  onTokenExpired: (user_id) {  // gives the user ID for which the token has expired
    log('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
  },
  onExit: (reason, user_id) {  // indicates that the user with given user ID has closed the SDK and gives an appropriate reason for it
    log('onExit: $reason, $user_id');
  },
  onConnectionFailure: (reason, work_platform_id, user_id) {  // 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('onConnectionFailure: $reason, $work_platform_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.

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_flutter_sdk_version": "<SemVer string>",
//   "connect_ios_sdk_version": "<SemVer string>",
//   "min_supported_ios_version": "<iOS version string>",
//   "max_supported_ios_version": "<iOS version string>",
//   "connect_android_sdk_version": "<SemVer string>",
//   "min_supported_android_version": "<android SDK version string>",
//   "max_supported_android_version": "<android SDK version string>"
// }

Was this helpful?