Getting Started

Connect SDK is used to connect creator's work platforms with the InsighIQ API. It serves as the client-side interface where creators securely connect their platforms, enabling access to their identity, income, and work information via the InsightIQ API. Connect SDK is compatible with all modern browsers across various platforms.

Implementation Guide

API Credentials

InsightIQ APIs are authenticated using client ID and secret. To maintain security, APIs must be called only from your server and never from your app / frontend. To get your API credentials, register on our dashboard.

Testing in the Staging

We recommend integrating with the staging environment before going live with InsightIQ. It allows you to generate SDK tokens, launch the Connect SDK, and simulate the user flow by connecting work platform accounts and retrieving identity, engagement, and income data. It also helps in seeing how different SDK token configurations affect the connect SDK flow.

1. Create SDK token

Execute at: backend

Generate a short-lived SDK token by sending a request to create an SDK token API. This token is valid for one week.

POST https://api.staging.insightiq.ai/v1/sdk-token
Authorization: Basic 
Content-Type: application/json

{
  "user_id": "John Doe",
  "products": [
    "IDENTITY",
    "IDENTITY.AUDIENCE",
    "ENGAGEMENT",
    "ENGAGEMENT.AUDIENCE",
    "INCOME"
  ]
}

2. Initialize the SDK with token and other parameters

Execute at: frontend

After the SDK token is obtained, initialize the SDK using the token and the following required parameters:

• client_display_name: The name of your application displayed to creators while granting access.

• environment: The mode for the SDK, which can be either staging (for testing) or production.

• user_id: A unique identifier for user returned by the InsightIQ API after creating a user. For more details, refer Create a user API.

• work_platform_id: A unique identifier for work platforms allows creators to skip platform selection screen and directly connect a specific work platform. For more details, refer Retrieve all work platforms API.

3. Open the SDK

Execute at: frontend

After initializing the SDK, you can open it to allow creators to connect their work platforms. For a detailed walkthrough of the creator's experience, refer Connect SDK Flow.

4. Listen for connection events

Execute at: frontend

After a creator successfully connects their account, the SDK emits an onAccountConnected event. This event contains critical data such as account_id and user_id, which can be transferred to your backend and start fetching data.

Additionally, a webhook event ACCOUNTS.CONNECTED is sent to your backend. While both the SDK event and the webhook provide similar data, webhooks are generally recommended.

In general, webhooks are a more reliable source of data. They are delivered directly from our server to your server, independent on the user's device or internet connection. Although, since webhooks are not as quick and real-time as the events being triggered on the frontend, relying on webhooks to update frontend is not recommended.

Recommended Workflow for an optimal integration:

Use front-end events for real-time updates and to provide feedback to the user and update your app and use the webhooks to start the actual data fetching via InsighIQ

Going live in Staging and Production environments

The integration steps for staging and production environments are identical to the staging setup. The key difference is that platform-related pages in these environments are not mocked, they require actual user accounts to establish connections.

To transition from staging to production:

• Update the API URL and credentials on your backend to match the staging or production environment settings.

• Set the environment parameter in the SDK configuration to staging or production wherever applicable.

Monitoring SDK Events

SDK events provide visibility into what is happening as the creator navigates through InsighIQ SDK. Use these events to track a creator's journey through the Connect SDK flow and listen for success and error messages.

Client-side SDKs

InsightIQ provides SDKs for Web, iOS, Android, Flutter, and React Native, making integration seamless across platforms. For more details, check out SDKs published on our Github.

For detailed installation and usage instructions, visit the documentaion page for Connect SDKs.

Sample apps

Explore the sample apps on our Github page to test InsighIQ APIs and Connect SDKs without integrating the SDK on your application. The boilerplate apps are great to quickly get started.