​
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:

  1. Enhanced speed and stability in loading merchant flows.
  2. More streamlined initialization of the SDK.
  3. Simplified event handling, more informative event messaging, and uniform naming conventions for easier debugging.
  4. 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

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

After

Dart
_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

Dart
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

Dart
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.01.0 Event Name
refresh session requestREFRESH_SESSION_REQUEST
merchant clickedMERCHANT_CLICKED
login startedLOGIN_STARTED
authenticatedAUTHENTICATED
otp requiredOTP_REQUIRED
security questions requiredSECURITY_QUESTIONS_REQUIRED
approval requiredAPPROVAL_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

Dart
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

Dart
void onError(KnotError error) {
  switch (error) {
    case KnotError.INVALID_SESSION:
      print("Error: INVALID_SESSION - ${error.message}");
      break;
    case KnotError.EXPIRED_SESSION:
      print("Error: EXPIRED_SESSION - ${error.message}");
      break;
    case KnotError.INVALID_CLIENT_ID:
      print("Error: INVALID_CLIENT_ID - ${error.message}");
      break;
    case KnotError.INTERNAL_ERROR:
      print("Error: INTERNAL_ERROR - ${error.message}");
      break;
	case KnotError.MERCHANT_ID_NOT_FOUND:
      print("Error: MERCHANT_ID_NOT_FOUND - ${error.message}");
      break;
  }
}

Error Types

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

Error CaseDescription
.invalidSessionThe session is invalid.
.expiredSessionThe session has expired.
.invalidClientIdThe client ID is invalid.
.internalErrorAn internal error occurred.
.merchantIdNotFoundThe 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

Dart
_knotapiFlutterPlugin.closeKnotSDK();

After

Dart
_knotapiFlutterPlugin.close();