idmax-button-creator

A JavaScript SDK to create and customize buttons for various identity verification providers. This SDK allows seamless integration with providers like CLEAR, PLAID, LA Wallet, DigiLocker, and more.

Table of Contents

• Getting a Token
• Installation
  • Using npm
  • Using Script Tag
• Usage
  • Initialization
  • Options
• Event Callbacks
• Examples
  • React Integration
  • Vanilla JavaScript Integration
• License
• Changelog

Getting a Token

To use the IDMax Button Creator SDK, you need to obtain an API token. Please refer to the API Documentation to get a token.

Installation

You can install the package using npm or include it via a script tag.

Using npm

npm install idmax-button-creator

Using Script Tag

Include the following script and CSS files in your HTML file. You can use the latest version or specify a version in the URL.

<script
  defer
  src="https://idmax.s3.amazonaws.com/latest/idmax-button-creator.min.js"
></script>
<link
  rel="stylesheet"
  href="https://idmax.s3.amazonaws.com/latest/idmax-button-creator.min.css"
/>

To use a specific version (e.g., version 1.2.0), you can use:

<script
  defer
  src="https://idmax.s3.amazonaws.com/v1.2.1/idmax-button-creator.min.js"
></script>
<link
  rel="stylesheet"
  href="https://idmax.s3.amazonaws.com/v1.2.1/idmax-button-creator.min.css"
/>

Usage

Initialization

To initialize the ButtonCreator, create a new instance with the minimum required options.

import ButtonCreator from "idmax-button-creator";

const buttonCreator = new ButtonCreator({
  providers: ["clear", "plaid"],
  targetElement: document.getElementById("button-container"),
  token: "YOUR_TOKEN",
  target: { email: "[email protected]" }, // Required
});

Options

providers

An array of provider keys to display as buttons. Available providers:

• clear
• plaid
• mdl_la
• digital_id_connect
• one_id
• digilocker

method

The method for handling verification. Options:

• popup (default)
• redirect

targetElement

The DOM element where the buttons will be appended.

token

The API token obtained from the IDMax API. Required.

target

An object containing the target user's information. Email is required. Available parameters:

• email (required)
• fn (first name)
• ln (last name)
• addr (address)
• city
• state
• zip
• dob (date of birth, format: YYYYMMDD)
• phone

resultMessages

An object containing the messages to display for different results.

resultMessages: {
  success: {
    title: "Success",
    subtitle: "You have successfully verified your identity.",
  },
  failure: {
    title: "Failure",
    subtitle: "Verification failed. Please try again.",
  },
  error: {
    title: "Error",
    subtitle: "An error occurred. Please try again.",
  },
}

styles

Customize the appearance of buttons and modal.

styles: {
  buttons: {
    radius: '8px', // Button border radius
    gap: '10px',   // Space between buttons
    padding: '10px 20px' // Button padding
  },
  modal: {
    overlay: {
      color: '#000', // Overlay color
      backgroundOpacity: 0.5, // Overlay opacity
      blur: 2 // Overlay blur
    },
    content: {
      borderRadius: '12px' // Modal content border radius
    }
  }
}

settings

Customize the behavior of the verification process.

settings: {
  providers: {
    digital_id_connect: {
      showWorksWith: false, // Show "Works with" text for Digital ID Connect provider
    },
  },
  language: "en", // Language for the verification process
  lazyLoad: true, // Lazy load the SDK
  autoClose: true, // Automatically close the modal on completion
}

Event Callbacks

onComplete(data)

Called when the verification process is completed.

function onComplete(data) {
  console.log("Verification completed:", data);
  buttonCreator.closeModal();
}

Example Payload:

{
  "request_id": "abc123"
}

onError(error)

Called when an error occurs during the verification process.

function onError(error) {
  console.error("Verification error:", error);
}

Example Payload:

{
  "type": "ERROR",
  "message": "BAD TOKEN"
}

onClose()

Called when the modal is closed.

function onClose() {
  console.log("Modal closed");
}

onInit(data)

Called when a provider is initialized.

function onInit(data) {
  console.log("Provider initialized:", data);
}

Example Payload:

{
  "provider": "clear",
  "request_id": "abc123"
}

Methods

closeModal()

Manually closes the modal.

buttonCreator.closeModal();

createButtons()

Creates the buttons for the providers.

buttonCreator.createButtons();

Examples

React Integration

import React, { useEffect, useRef, useState } from "react";
import {
  ButtonCreator,
  OnCompleteData,
  OnErrorData,
  OnInitData,
  ProviderKey,
} from "idmax-button-creator";
import "idmax-button-creator/dist/idmax-button-creator.css";

const App: React.FC = () => {
  const buttonContainerRef = useRef<HTMLDivElement>(null);
  const buttonCreatorRef = useRef<ButtonCreator | null>(null);
  const [sdkInitialized, setSdkInitialized] = useState(false);

  const initializeSdk = () => {
    const token = "1c6b92a1-d82e-43e2-9e4e-55e105bc7a48";
    const email = "[email protected]";
    const providers: ProviderKey[] = [
      "clear",
      "plaid",
      "mdl_la",
      "digital_id_connect",
      "digilocker",
      "one_id",
    ];

    buttonCreatorRef.current = new ButtonCreator({
      targetElement: buttonContainerRef.current!,
      token: token,
      target: { email: email, phone: "555-555-5555" },
      method: "popup",
      providers: providers,
      data: {
        reference: "12345", // any string value you want returned
        additional: {
          // any key value pairs you want returned
          key1: "12345",
          key2: "12345",
        },
      },
      settings: {
        providers: {
          digital_id_connect: { showWorksWith: false },
        },
        lazyLoad: true, // false by default
        autoClose: true, // false by default
        language: "", // en by default
      },
      resultMessages: {
        success: {
          title: "Success",
          subtitle: "You have successfully verified your identity.",
        },
        failure: {
          title: "Failure",
          subtitle: "Verification failed. Please try again.",
        },
        error: {
          title: "Error",
          subtitle: "An error occurred. Please try again.",
          specific: {
            alreadyVerified: {
              title: "You have already been verified",
              subtitle: "Please contact customer support",
            },
            velocity: {
              title: "Too many attempts",
              subtitle:
                "You have exceeded the number of verification attempts. Please try again later.",
            },
            pending: {
              title: "Verification pending",
              subtitle:
                "Your verification is currently pending. Please wait for further instructions.",
            },
            token: {
              title: "Invalid token",
              subtitle:
                "The token provided is not valid. Please check and try again.",
            },
          },
        },
      },
      styles: {
        buttons: {
          radius: "10px",
          gap: "15px",
          padding: "10px 20px",
        },
        modal: {
          overlay: {
            color: "#000",
            backgroundOpacity: 0.5,
            blur: 2,
          },
          content: {
            borderRadius: "20px",
          },
        },
      },
      onInit: (data: OnInitData) => {
        console.log("Init: ", data);
      },
      onClose: () => {
        console.log("The modal was closed by the user");
      },
      onComplete: (data: OnCompleteData) => {
        console.log("Done: ", data);
        /** You can do a manual close of the modal if autoClose is false
          if (buttonCreatorRef.current) {
            buttonCreatorRef.current.closeModal();
          }
        */
      },
      onError: (error: OnErrorData) => {
        console.error("Error: ", error.message);
      },
    });

    setSdkInitialized(true);
  };

  useEffect(() => {
    initializeSdk();

    return () => {
      if (buttonCreatorRef.current) {
        buttonCreatorRef.current.destroy();
        console.log("SDK instance destroyed");
        setSdkInitialized(false);
      }
    };
  }, []);

  const handleCreateButtons = () => {
    buttonCreatorRef.current?.createButtons();
  };

  const handleDestroy = () => {
    if (buttonCreatorRef.current) {
      buttonCreatorRef.current.destroy();
      console.log("SDK instance destroyed via button");
      setSdkInitialized(false);
    }
  };

  const handleLoadSdk = () => {
    if (!sdkInitialized) {
      initializeSdk();
      console.log("SDK instance loaded");
    }
  };

  return (
    <div style={{ width: "400px", marginLeft: "40px", marginTop: "10px" }}>
      <button onClick={handleCreateButtons} disabled={!sdkInitialized}>
        Load Buttons
      </button>
      <button onClick={handleDestroy} disabled={!sdkInitialized}>
        Destroy SDK
      </button>
      <button onClick={handleLoadSdk} disabled={sdkInitialized}>
        Load SDK
      </button>

      <div style={{ marginTop: "10px" }} ref={buttonContainerRef}></div>
    </div>
  );
};

export default App;

Vanilla JavaScript Integration

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script
      defer
      src="https://idmax.s3.amazonaws.com/latest/idmax-button-creator.min.js"
    ></script>
    <link
      rel="stylesheet"
      href="https://idmax.s3.amazonaws.com/latest/idmax-button-creator.min.css"
    />
    <title>IDMax Button Creator Example</title>
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        const buttonCreator = new IDMax.ButtonCreator({
          providers: ["clear", "plaid"],
          method: "popup",
          token: "YOUR_API_TOKEN",
          target: { email: "[email protected]" }, // Required
          targetElement: document.getElementById("button-container"),
          settings: {
            lazyLoad: true, // Required to manually create buttons later
          },
          resultMessages: {
            success: {
              title: "Success",
              subtitle: "You have successfully verified your identity.",
            },
            failure: {
              title: "Failure",
              subtitle: "Verification failed. Please try again.",
            },
            error: {
              title: "Error",
              subtitle: "An error occurred. Please try again.",
            },
          },
          styles: {
            buttons: {
              radius: "8px",
              gap: "10px",
              padding: "10px 20px",
            },
            modal: {
              overlay: {
                color: "#000",
                backgroundOpacity: 0.5,
                blur: 2,
              },
              content: {
                borderRadius: "12px",
              },
            },
          },
          onComplete: function (data) {
            console.log("Verification completed:", data);
            buttonCreator.closeModal();
          },
          onError: function (error) {
            console.error("Verification error:", error);
          },
          onClose: function () {
            console.log("Modal closed");
          },
          onInit: function (data) {
            console.log("Provider initialized:", data);
          },
        });

        buttonCreator.createButtons();
      });
    </script>
  </head>

  <body>
    <div id="button-container"></div>
  </body>
</html>

Changelog

Version 1.2.2

• Fixes:

• Fixed issue with autoClose triggering incorrectly in receiveMessage function by checking the origin and the message payload. This was causing the modal to auto close before the iFrame url was set.