> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter 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:

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 `open` action now requires a `KnotConfiguration` which is now `Knot.open(knotConfiguration)`.

**Before**

```dart Dart theme={"system"}
_knotapiFlutterPlugin.openCardOnFileSwitcher(KnotConfiguration(
      sessionId: SESSION_ID,
      clientId: CLIENT_ID,
      environment: ENVIRONMENT,
    ));
```

**After**

```dart Dart theme={"system"}
_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 Dart theme={"system"}
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 Dart theme={"system"}
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**

```dart Dart theme={"system"}
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 Dart theme={"system"}
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 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

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

**Changes**

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

**Before**

```dart Dart theme={"system"}
_knotapiFlutterPlugin.closeKnotSDK();
```

**After**

```dart Dart theme={"system"}
_knotapiFlutterPlugin.close();
```