> ## 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.

<Card title="View on pub.dev" icon="flutter" href="https://pub.dev/packages/sandbox_digilocker_sdk">
  Check out the package on pub.dev for latest version and updates
</Card>

<Steps>
  <Step title="Create a session" stepNumber={1} titleSize="h2">
    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](../../endpoints/create-session) endpoint to generate this session.
    This is a **server-side API call** that uses [Sandbox Authentication](/api-reference/authenticate) to validate your credentials.

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

  <Step title="Install the package" stepNumber={2} titleSize="h2">
    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
  </Step>

  <Step title="Integrate the SDK" stepNumber={3} titleSize="h2">
    Import the SDK, set your API key, configure options, and launch the DigiLocker flow.

    <AccordionGroup>
      <Accordion title="3.1 Basic implementation" defaultOpen>
        ```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
            },
          },
        );
        ```
      </Accordion>

      <Accordion title="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"
          }
        }
        ```

        <ParamField body="session_id" type="string" required placeholder="a7fac865-61a9-4589-b80c....">
          Unique session ID generated when Create Session API is called.
        </ParamField>

        <ParamField body="brand" type="object" required>
          Configuration for branding displayed in the DigiLocker interface.

          <Expandable title="child attributes">
            <ParamField body="name" type="string" required>
              Display name of your business or app shown during the DigiLocker flow.
            </ParamField>

            <ParamField body="logo_url" type="string" required>
              Publicly accessible HTTPS URL of your logo displayed within the SDK.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="theme" type="object" required>
          Appearance configuration for the SDK.

          <Expandable title="child attributes">
            <ParamField body="mode" type="string" required>
              Sets the overall appearance of the SDK. Accepts `"light"` or `"dark"`.
            </ParamField>

            <ParamField body="seed" type="string" required>
              Primary brand color used in the SDK interface. Accepts a hex code.
            </ParamField>
          </Expandable>
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Handle SDK events" stepNumber={4} titleSize="h2">
    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](../../endpoints/get-session-status) endpoint from your backend.
  </Step>
</Steps>

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

<CardGroup cols={3}>
  <Card title="Create Session API" icon="code" href="../../endpoints/create-session">
    Learn how to create sessions for the SDK
  </Card>

  <Card title="Session Status API" icon="clock" href="../../endpoints/get-session-status">
    Monitor session progress and status
  </Card>

  <Card title="Get Document API" icon="file" href="../../endpoints/get-document">
    Retrieve document data after completion
  </Card>
</CardGroup>