> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sandbox.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter

> Integrate DigiLocker SDK into your Flutter application

Integrate DigiLocker document retrieval into your Flutter app using the native SDK. The SDK provides an embedded interface that works on both iOS and Android.

> **[View on pub.dev](https://pub.dev/packages/sandbox_digilocker_sdk)**
>
> Check out the package on pub.dev for latest version and updates

## 1. Create a session

Before initializing the SDK, you must create a **unique session**.
Each SDK instance requires its own session to ensure secure and independent interactions.

Use the [Create Session](https://developer.sandbox.co.in/api-reference/kyc/digilocker-sdk/endpoints/create-session.md) endpoint to generate this session.
This is a **server-side API call** that uses [Sandbox Authentication](https://developer.sandbox.co.in/api-reference/authenticate.md) to validate your credentials.

Once created, you'll receive a `session_id`, which you'll need when initializing the SDK on the client side.

## 2. Install the package

Add the DigiLocker SDK package to your Flutter project.

```bash theme={null}
flutter pub add sandbox_digilocker_sdk
```

Or add it manually to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  sandbox_digilocker_sdk: ^1.0.0
```

Requirements: Flutter SDK ^3.10.1

## 3. Integrate the SDK

Import the SDK, set your API key, configure options, and launch the DigiLocker flow.

> **3.1 Basic implementation**
>
> ```dart theme={null}
> import 'package:sandbox_digilocker_sdk/sandbox_digilocker_sdk.dart';
>
> // Set your API key
> DigilockerSDK.instance.setAPIKey('key_your_api_key_here');
>
> // Set event listener (optional)
> DigilockerSDK.instance.setEventListener(SDKEventListener());
>
> // Launch the SDK
> await DigilockerSDK.instance.open(
>   context: context,
>   options: {
>     'session_id': 'a7fac865-61a9-4589-b80c....', // Replace with your session ID from Step 1
>     'brand': {
>       'name': 'MoneyApp', // Your business or app name
>       'logo_url': 'https://i.imgur.com/vMd9Wcu.png', // Publicly accessible URL
>     },
>     'theme': {
>       'mode': 'light', // Options: 'light' or 'dark'
>       'seed': '#3D6838', // Primary color for theme customization
>     },
>   },
> );
> ```

> **3.2 SDK options reference**
>
> ```json theme={null}
> {
>   "session_id": "a7fac865-61a9-4589-b80c....",
>   "brand": {
>     "name": "MoneyApp",
>     "logo_url": "https://i.imgur.com/vMd9Wcu.png"
>   },
>   "theme": {
>     "mode": "light",
>     "seed": "#3D6838"
>   }
> }
> ```
>
> **session\_id** `string` *required*
>
> Unique session ID generated when Create Session API is called.
>
> **brand** `object` *required*
>
> Configuration for branding displayed in the DigiLocker interface.
>
> **child attributes**
>
> **name** `string` *required*
>
> Display name of your business or app shown during the DigiLocker flow.
>
> **logo\_url** `string` *required*
>
> Publicly accessible HTTPS URL of your logo displayed within the SDK.
>
> **theme** `object` *required*
>
> Appearance configuration for the SDK.
>
> **child attributes**
>
> **mode** `string` *required*
>
> Sets the overall appearance of the SDK. Accepts `"light"` or `"dark"`.
>
> **seed** `string` *required*
>
> Primary brand color used in the SDK interface. Accepts a hex code.

## 4. Handle SDK events

Set up an event listener to handle SDK events indicating session completion or cancellation.

```dart theme={null}
class SDKEventListener implements EventListener {
  @override
  void onEvent(Map<String, dynamic> event) {
    print('Received event: $event');
    
    final eventType = event['type'];
    
    if (eventType == 'in.co.sandbox.kyc.digilocker_sdk.session.completed') {
      // Documents were fetched successfully
      // Proceed with your application flow
      fetchDocumentsFromBackend(sessionId);
    } else if (eventType == 'in.co.sandbox.kyc.digilocker_sdk.session.closed') {
      // User closed the SDK
      print('User closed the SDK');
    }
  }
}
```

To programmatically verify the final status of a session, call the [Session Status](https://developer.sandbox.co.in/api-reference/kyc/digilocker-sdk/endpoints/get-session-status.md) endpoint from your backend.

## Event types

The SDK emits the following event types via the `EventListener`:

| Event Type | Description |
| - | - |
| `in.co.sandbox.kyc.digilocker_sdk.session.completed` | User successfully completed the DigiLocker flow and documents were retrieved |
| `in.co.sandbox.kyc.digilocker_sdk.session.closed` | User closed the SDK without completing the flow |

## API reference

### DigilockerSDK

The main SDK class that provides a singleton instance.

**Methods:**

`setAPIKey(String apiKey)`

* Sets the API key required to authenticate requests
* Parameters: `apiKey` (String) - The API key string starting with "key\_"
* Throws: Exception if the API key does not start with "key\_"

`open(BuildContext context, Map options)`

* Opens the SDK UI with the provided configuration
* Parameters:
  * `context` (BuildContext) - The BuildContext from which the SDK is accessed
  * `options` (Map) - Configuration options including session\_id, brand, and theme
* Throws: Exception if API key or required options are not set

`setEventListener(EventListener eventListener)`

* Registers an event listener to receive SDK events
* Parameters: `eventListener` (EventListener) - The event listener to register

### EventListener

Interface for receiving SDK events.

**Methods:**

`onEvent(Map event)`

* Called when an SDK event occurs
* Parameters: `event` (Map) - The event data containing event type and payload

## Next steps

> **[Create Session API](https://developer.sandbox.co.in/api-reference/kyc/digilocker-sdk/endpoints/create-session.md)**
>
> Learn how to create sessions for the SDK

> **[Session Status API](https://developer.sandbox.co.in/api-reference/kyc/digilocker-sdk/endpoints/get-session-status.md)**
>
> Monitor session progress and status

> **[Get Document API](https://developer.sandbox.co.in/api-reference/kyc/digilocker-sdk/endpoints/get-document.md)**
>
> Retrieve document data after completion


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.