Flutter

Overview

📘

Version 1.0 and later

Version 1.0 of the SDK introduces breaking changes that require changes in your application code if you had previously integrated an early version. See the Migration Guide for further details.

Documentation for older versions of the iOS SDK can be found here.

The Knot Link SDK provides a seamless way for end users to link their merchant accounts to your Flutter app, serving as the foundation for Knot's merchant connectivity platform. It is a client-side integration, consisting of initializing & configuring the SDK and handling events.

Installation

The Knot SDK can be installed using pub package manager.

flutter pub add knotapi_flutter

Import the SDK

import 'package:knotapi_flutter/knotapi_flutter.dart';
import 'package:knotapi_flutter/knotapi_configuration.dart';

Initialization

Your backend will create a session by calling Create Session and provide it to your frontend. To start a Knot session, you must first configure the session with a KnotConfiguration class. The configuration allows you to set the environment, product type, entry point, and other user experience configurations.

Configure the session

The KnotConfiguration class is used to initialize the SDK with specific parameters.

KnotConfiguration(
        sessionId: "695ce724-7f61-40f1-a410-cb0c0fcf9b7f",
        clientId: "3f4acb6b-a8c9-47bc-820c-b0eaf24ee771",
        environment: Environment.development, // or Environment.production
        product: Product.transactionLink, // or Product.cardSwitcher
        merchantIds: [17], // Optional value
        useCategories: false, // Optional value
        useSearch: false, // Optional value
        domainUrls: ["https://example.com"] // Optional value
        )

Open the session

To begin the flow, use the open method with a KnotConfiguration instance.

final _knot = KnotapiFlutter();

_knot.open(KnotConfiguration(
    sessionId: "INSERT_SESSION_ID",
    clientId: "INSERT_CLIENT_ID",
    environment: Environment.development, // or Environment.production
    product: Product.cardSwitcher // or Product.cardSwitcher
    ));

Single Merchant Flow

If you decide to use List Merchants to retrieve a list of merchants, list them in your app, and then open the SDK with a single merchant, you can do so by passing a merchant ID when configuring the session in the KnotConfiguration. More in Retrieving & Listing Merchants. The merchant ID is the same across all environments.

Although available, it is not recommended that you provide a long list of merchants in order to remove a few, but rather "hide" certain merchants that you desire from your Customer Dashboard.

Entry Points

In your app's user experience, you may choose to integrate Knot in one or multiple places (e.g. from different tabs or screens). How users behave when interacting with Knot from each of these "entry points" may vary and it will be useful for you to be able to differentiate these groups of users by entry point in order to assess the value of each entry point.

You can provide a value for the entry point in when configuring the session in the KnotConfiguration. This value will be returned in the AUTHENTICATED webhook.

Categories & Search

Users are presented with a list of merchants in the SDK (unless you provide a single merchant as described above). Accompanying the list is a set of categories and a search experience. Each of these components is visible to users by default (as set in Knot's backend).

You can choose to remove either of them by setting useCategories: false and useSearch: false in KnotConfiguration. This is not recommended.

Events

To receive updates from the SDK, import the following:

import 'dart:async';
import 'package:knotapi_flutter/events.dart';

Then, implement the example code found below.

onSuccess

This event is called when a user successfully logged in to the merchant and their card was switched. It takes a single argument KnotSuccess.

...
StreamSubscription<KnotSuccess>? _streamSuccess;

void initState() {
    super.initState();
    _streamSuccess = KnotapiFlutter.onSuccess.listen(_onSuccess);
}

void _onSuccess (KnotSuccess event) {
    Product product = event.product;
    String merchant = event.merchant;
    print("product: $product, merchant: $merchant");
}
...

onError

This event is called when an error occurs during SDK initialization and emits a KnotError enum with 4 cases, as described below.

...
StreamSubscription<KnotError>? _streamError;

void initState() {
    super.initState();
    _streamError = KnotapiFlutter.onError.listen(_onError);
}

void _onError (KnotError event) {
    String message = event.message;
    String errorCode = event.errorCode;
    String product = event.product;

    print("message: $message, errorCode: $errorCode, product: $product");
  }
...

onExit

This event is called when a user closes the SDK. It takes a single argument KnotExit.

...
StreamSubscription<KnotExit>? _streamExit;

void initState() {
    super.initState();
    _streamExit = KnotapiFlutter.onExit.listen(_onExit);
}

void _onExit (KnotExit event) {
    String product = event.type;

    print("product: $product");
  }
...

onEvent

This event is called when certain events occur in the SDK. With this callback, you will be able to understand how a user is progressing through their lifecycle of authenticating to a merchant. It takes a single argument KnotEvent.

...
StreamSubscription<KnotEvent>? _streamEvent;

void initState() {
    super.initState();
    _streamEvent = KnotapiFlutter.onEvent.listen(_onEvent);
}

void _onEvent (KnotEvent event) {
    Environment environment = event.environment
    Product product = event.product;
    String code = event.event
    String? merchant = event.merchant
    String? taskId = event.taskId
    Map<String, Object?> metaData  = event.metaData

    print("product: $product, environment: $environment, code: $code, merchant: $merchant, metaData: $metaData");
}
...

The following list contains all possible events emitted in the KnotEvent.event property.

Other Options

Close the SDK

If you need to explicitly close the SDK, use the below method, otherwise end users will naturally close the SDK as they interact with the interface.

_dart.close();

Maintain cookies

Knot clears cookies for security purposes. If your app relies on cookies, you can allowlist specific domains using the domainUrls configuration in KnotConfiguration. This is uncommon.

// The allowed domains for cookies to add as a parameter in KnotConfiguration
KnotConfiguration(
      sessionId: "695ce724-7f61-40f1-a410-cb0c0fcf9b7f",
      clientId: "3f4acb6b-a8c9-47bc-820c-b0eaf24ee771",
      environment: Environment.development, // or Environment.production
      product: Product.transactionLink, // or Product.cardSwitcher
      merchantIds: [17], // Optional value
      useCategories: false, // Optional value
      useSearch: false, // Optional value
      domainUrls: ["https://example.com", "https://secure.example.com"] // Optional value
      )