Integration Guide

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 endpoint to generate this session.
This is a server-side API call that uses Sandbox Authentication 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. Integrate the SDK on the Client Side

After creating the session, the next step is to integrate the DigiLocker SDK into your client-side application.
You’ll add a “Fetch with DigiLocker” button that triggers the DigiLocker flow.

2.1 Example: “Fetch with DigiLocker” Button


<script src="https://sdk.sandbox.co.in/kyc/digilocker/sdk.js"></script>

<script>
  function launch() {
    // Define a custom event listener to handle SDK events
    class EventListener extends DigilockerSDK.EventListener {
      constructor(callback) {
        super();
        this.callback = callback;
      }
      onEvent(event) {
        if (this.callback) {
          this.callback(event);
        }
      }
    }
    
    // Define a callback function to process events from the SDK
    const handleEvent = (event) => {
      console.log("Received event:", event);
    };

    // Initialize the event listener with your callback
    const eventListener = new EventListener(handleEvent);
    DigilockerSDK.setEventListener(eventListener);


    // Set your API key
    DigilockerSDK.setAPIKey("YOUR_API_KEY");

    // Configure the SDK options
    const 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://example.com/your_logo", // Publicly accessible URL of your logo
      },
      theme: {
        mode: "light", // Options: "light" or "dark"
        seed: "#3D6838", // Primary color for theme customization
      },
    };

    // Launch the DigiLocker SDK
    DigilockerSDK.open(options);
  }
</script>

<button onclick="launch()">Fetch with DigiLocker</button>

2.2 SDK Options

The options object customizes how the DigiLocker SDK behaves and appears within your application.

{
  "session_id": "a7fac865-61a9-4589-b80c....",
  "brand": {
    "name": "MoneyApp",
    "logo_url": "https://example.com/your_logo"
  },
  "theme": {
    "mode": "light",
    "seed": "#3D6838"
  }
}

Parameter Details

Key	Type	Description	Example
`session_id`	string	Unique identifier for the SDK session. Connects the client SDK to the session created on your backend.	`"a7fac865-61a9-4589-b80c..."`
`brand`	object	Configuration for branding displayed in the DigiLocker interface.	—
`brand.name`	string	Display name of your business or app shown during the DigiLocker flow.	`"MoneyApp"`
`brand.logo_url`	string	Publicly accessible HTTPS URL of your logo displayed within the SDK.	`"https://example.com/your_logo"`
`theme`	object	Appearance configuration for the SDK.	—
`theme.mode`	string	Sets the overall appearance of the SDK. Accepts `"light"` or `"dark"`.	`"light"`
`theme.seed`	string	Primary brand color used in the SDK interface. Accepts a hex code.	`"#3D6838"`

3. Handle Session Success and Failure

After a user interacts with the DigiLocker SDK, various events are emitted that indicate the outcome of the session — whether it succeeded, failed, or was canceled.

Your event listener (defined earlier) receives these events. You can handle them as follows:

const handleEvent = (event) => {
  console.log("Event received:", event);
  
  switch (event.type) {
    case "in.co.sandbox.kyc.digilocker_sdk.session.completed":
      // The documents were fetched from digilocker successfully
      // Proceed with your application flow
      break;

    case "in.co.sandbox.kyc.digilocker_sdk.session.closed":
      // The user closed or exited out of the sdk
      break;

    default:
      console.log("Unhandled event:", event);
  }
};

To programmatically verify the final status of a session, you can call the Session Status endpoint from your backend.
This is useful for confirming completion or troubleshooting unexpected results, especially in cases where the client event might have been interrupted.

Summary

Create a session using your backend and store the session_id.
Integrate the SDK on the client side and configure it with your brand and theme.
Listen for SDK events to determine success, failure, or cancellation.
Verify session status using the server-side API for additional confirmation.