Migrating to Version 1.0+

Overview

To simplify your application logic and integration with the Knot Flutter SDK, Version 1.0 includes a number of breaking changes that may affect the way your integration works or behaves.

The new version includes a number of significant improvements:

Enhanced speed and stability in loading merchant flows.
More streamlined initialization of the SDK.
Simplified event handling, more informative event messaging, and uniform naming conventions for easier debugging.
Improved maintainability and foundations for new feature compatibility.

Breaking Changes

Configuring and opening the Knot SDK has changed significantly in Flutter Version 1.0 and requires some refactoring in order to initialize the SDK with a session. Events and Errors now provide additional values to debug with.

Session Initialization

Changes

.openCardOnFileSwitcher is replaced with a more flexible .open.
The product type is now defined by Product enum values .card_switcher | .transaction_link.
The open action now requires a KnotConfiguration which is now Knot.open(knotConfiguration).

Before

_knotapiFlutterPlugin.openCardOnFileSwitcher(KnotConfiguration(
      sessionId: SESSION_ID,
      clientId: CLIENT_ID,
      environment: ENVIRONMENT,
    ));

After

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

Event handling

Changes

The onEvent type now provides the environment and product the event originanted from.
The KnotError type provides improved error descriptions and product type.
The KnotSuccess type now provides a product type and a metaData map.

Before

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

...
class _MyAppState extends State<MyApp> {
  final _knotapiFlutterPlugin = KnotapiFlutter();
  StreamSubscription<KnotEvent>? _streamEvent;
  StreamSubscription<KnotSuccess>? _streamSuccess;
  StreamSubscription<KnotError>? _streamError;
  StreamSubscription<KnotExit>? _streamExit;

  @override
  void initState() {
    super.initState();
    _streamError = KnotapiFlutter.onError.listen(_onError);
    _streamEvent = KnotapiFlutter.onEvent.listen(_onEvent);
    _streamExit = KnotapiFlutter.onExit.listen(_onExit);
    _streamSuccess = KnotapiFlutter.onSuccess.listen(_onSuccess);
  }

...

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

  void _onError (KnotError event) {
    String type = event.type;
    String errorMessage = event.errorMessage;
    print("type: $type, errorMessage: $errorMessage");
  }

  void _onError (KnotError event) {
    String type = event.type;
    String name = event.event;
    String taskId = event.taskId;
    String merchantName = event.merchant;
    print("eventName: $eventName, type: $type, event: $name, taskId: $taskId, merchant: $merchantName");
  }

  void _onExit (KnotExit event) {
    String type = event.type;
    print("eventName: _onExit, type: $type");
  }

After

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

...
class _MyAppState extends State<MyApp> {
  final _knotapiFlutterPlugin = KnotapiFlutter();
  StreamSubscription<KnotEvent>? _streamEvent;
  StreamSubscription<KnotSuccess>? _streamSuccess;
  StreamSubscription<KnotError>? _streamError;
  StreamSubscription<KnotExit>? _streamExit;

  @override
  void initState() {
    super.initState();
    _streamError = KnotapiFlutter.onError.listen(_onError);
    _streamEvent = KnotapiFlutter.onEvent.listen(_onEvent);
    _streamExit = KnotapiFlutter.onExit.listen(_onExit);
    _streamSuccess = KnotapiFlutter.onSuccess.listen(_onSuccess);
  }

...

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

  void _onError (KnotError event) {
    String type = event.product;
    String message = event.message;
    print("eventName: _onError, type: $type, message: $message");
  }

  void _onEvent (KnotEvent event) {
    Product type = event.product;
    String name = event.event;
    String? taskId = event.taskId;
    Map<String, Object?> metaData = event.metaData;
    print("eventName: _onEvent, type: $type, event: $name, taskId: $taskId, metaData: $metaData");
  }

  void _onExit (KnotExit event) {
    String type = event.type;
    print("eventName: _onExit, type: $type");
  }

Event Names

The SDK now maps raw event names to standardized event names for easier handling.

Event Name Prior to 1.0	1.0 Event Name
refresh session request	REFRESH_SESSION_REQUEST
merchant clicked	MERCHANT_CLICKED
login started	LOGIN_STARTED
authenticated	AUTHENTICATED
otp required	OTP_REQUIRED
security questions required	SECURITY_QUESTIONS_REQUIRED
approval required	APPROVAL_REQUIRED

Error Handling

Error handling has been improved with more structured and meaningful error messages.

Changes

Errors are now encapsulated in the KnotError enum.
Each error has a human-readable description (errorDescription) and a unique error code (errorCode).
Improved clarity and consistency across error messages.

Before

void _onError (KnotError event) {
    String eventName = event.eventName;
    String type = event.type;
    String errorMessage = event.errorMessage;
    String errorCode = event.errorCode;
    print("eventName: $eventName, type: $type, errorCode: $errorCode, errorMessage: $errorMessage");
  }

After

void _onError (KnotError event) {
    String eventName = event.eventName;
    String type = event.type;
    String errorMessage = event.errorMessage;
    String errorCode = event.errorCode;
    print("eventName: $eventName, type: $type, errorCode: $errorCode, errorMessage: $errorMessage");
  }

Error Types

The Knot SDK provides predefined error cases for you to handle based on your own needs.

Error Case	Description
.invalidSession	The session is invalid.
.expiredSession	The session has expired.
.invalidClientId	The client ID is invalid.
.internalError	An internal error occurred.
.merchantIdNotFound	The merchant ID is required when product type = transaction_link.

Closing the SDK

Most apps do not use the explicit close method, as it is infrequently applicable to the integration with the Knot SDK.

Changes

Closing the SDK is now statically accessed via _knotapiFlutterPlugin.close() as opposed to _knotapiFlutterPlugin.closeKnotSDK().

Before

Closing the SDK is now statically accessed via _knotapiFlutterPlugin.close() as opposed to _knotapiFlutterPlugin.closeKnotSDK().

After

Closing the SDK is now statically accessed via _knotapiFlutterPlugin.close() as opposed to _knotapiFlutterPlugin.closeKnotSDK().