React Example

Authentication

For security reasons, you will first have to allowlist the URL of the website or web app on which the embedded flows will be hosted. This can be done from the 'Settings' tab on dashboard.aiprise.com under 'IFrame Origin Allowlist'.

Please note that if the source is not authorized, an error message saying Unable to create session. Please try again. will appear. To identify the precise hostname that needs to be allowlisted, you can examine the console.

Install the AiPrise Web SDK

Start by running the following command in the root folder of your React project:

npm i aiprise-web-sdk

Option 1: Web Button

This will integrate our verification button into your app. On clicking it, a modal will be launched where the user data will be collected. The template-id is the only required attribute. You can add others as per your requirements.

Basic Usage

import "aiprise-web-sdk";

export const SomeRandomComponent = () => {
  return (
    <div>
      <aiprise-button 
        template-id="YOUR_TEMPLATE_ID"
        mode="SANDBOX/PRODUCTION"
      />
    </div>
  );
};

Advanced Usage

Apart from template-id, there are a few more props that you can pass. These props allow you to change things like the button text, color, logo image, etc. All of them are listed in the example below.

In addition to the props, there are also five events fired by the button which you can listen to:
(i) started: Will be fired after the session starts. i.e. when the user clicks on the button, the modal opens and a new session gets created (after the loading screen is completed).
(ii) abandoned: Will be fired when the user quits out of the verification flow by clicking the close button and confirming that they want to stop the verification.
(iii) successful: This will be fired when the user completes filing out the entire verification form and reaches the last page. They may not have clicked the close button yet so the modal is still visibile at this point but no other information has to be collected from them. Also, "successful" does not mean that the KYC is approved. It just means form is successfully filled by the user.
(iv) continue: This will be fired AFTER the user clicks the close or continue button on the last page. The SDK will handle closing of the modal automatically in that case so no action is required on your end. The event is just in case you want to perform any task in your application after this point.
(v) error: This event is fired in case the session creation filed. This can happen for a number of reasons like invalid template ID, using the SDK outside your allowlisted hosts, etc. You can check the error message in the console to see why it's happening.

import { useEffect, useRef } from "react";

import "aiprise-web-sdk";

export const SomeRandomComponent = () => {
  const verifyButtonRef = useRef<HTMLElement>(null);

  useEffect(() => {
    // Started Event
    verifyButtonRef.current!.addEventListener("aiprise:started", function (e) {
      console.log("Session started with ID: " + e.detail.verification_session_id);
    });

    // Abandoned Event
    verifyButtonRef.current!.addEventListener("aiprise:abandoned", function (e) {
      console.log("Session with ID " + e.detail.verification_session_id + " was abandoned.");
    });

    // Successful Event
    verifyButtonRef.current!.addEventListener("aiprise:successful", function (e) {
      console.log("Session with ID " + e.detail.verification_session_id + " was successful.");
    });

    // Continue Event
    verifyButtonRef.current!.addEventListener("aiprise:continue", function (e) {
      console.log("Session with ID " + e.detail.verification_session_id + " was continued.");
    });

    // Error Event
    verifyButtonRef.current!.addEventListener("aiprise:error", function () {
      console.log("Unable to start session. Check your console for errors.");
    });
  }, []);

  return (
    <div>
      <aiprise-button
        ref={verifyButtonRef}
        template-id="YOUR_TEMPLATE_ID"
        mode="SANDBOX/PRODUCTION"
        callback-url="http://yourcallbackurl.com"
        client-reference-id="SOME_ID_YOU_WANT_TO_ASSOCIATE_WITH_YOUR_REQUEST"
        client-reference-data={JSON.stringify({ some_data: "some_value" })}
        user-data={JSON.stringify({
          first_name: "Your Users First Name",
          middle_name: "Your Users Middle Name",
          last_name: "Your Users Last Name",
          date_of_birth: "YYYY-MM-DD",
          phone_number: "+11234567890",
          email_address: "[email protected]",
          ip_address: "0.0.0.0",
          address: {
            address_street_1: "...",
            address_street_2: "...",
            address_city: "...",
            address_state: "...",
            address_zip_code: "...",
            address_country: "...",
          },
        })}
        icon="YOUR_40X40_LOGO_URL"
        title="YOUR_BUTTON_TEXT"
        color="YOUR_BRAND_HEX_CODE_WITH_#"
        text-color="BUTTON_TEXT_COLOR_HEX_CODE_WITH_#"
      />
    </div>
  );
};

For Applications with Server Side Rendering (SSR)

This component needs to access the window object for working. But on SSR frameworks like Next.js, window will be null on the server. This will cause your application to throw an error when you import aiprise-web-sdk.

To solve this issue, you just need to change how you import import the package:

// import "aiprise-web-sdk"; <= Don't add an import here...

export const MySSRComponent = () => {
  
  const importAiPriseWebSdk = async () => {
    await import("aiprise-web-sdk");
  };
  
  useEffect(() => {
    importAiPriseWebSdk(); // Import it dynamically on the client side
  }, []);
  
  // ...
};

Styling the Button

In your stylesheet, just write the button's class name and add the CSS properties you want to apply:

.aiprise-button {
    margin-top: 16px;
    margin-left: 16px;
    /* Other CSS stuff... */
}

Note: Avoid adding CSS properties to the inner elements of the button like the icon or the title div. These can change in future versions of the SDK. Only add CSS to the root button element using the aiprise-button class.

Option 2: Web Frame

This option allows you to integrate the verification flow directly into your website or app using an iframe. You can do your styling in a div that surrounds the iframe. Here, you take the responsibility or showing the verification flow (after some user action) and hiding it when the user has filled the entire form.

Just like the button, the template-id is the only required attribute. You can add others as per your needs.

Basic Usage

import "aiprise-web-sdk";

export const SomeRandomComponent = () => {
  return (
    <div style={{ width: "400px", height: "850px" }}>
        <aiprise-frame
          template-id="YOUR_TEMPLATE_ID"
          mode="SANDBOX/PRODUCTION"
        />
    </div>
  );
};

Advanced Usage

Similar to the button component, you can pass props here to customize the color (of the loading spinner) or the logo image, etc. Full list of attributes are visible in the example below.

Also similar to the button, there are events that you can listen to: started, successful, continue, error.
Note: There is no "abandoned" event here unlike the button since iframe's can be abandoned. It's always visible till the host application i.e. your website or app hides it.

import { useEffect, useRef } from "react";

import "aiprise-web-sdk";

export const SomeRandomComponent = () => {
  const verifyFrameRef = useRef<HTMLElement>(null);

  useEffect(() => {
    // Started Event
    verifyFrameRef.current!.addEventListener("aiprise:started", function (e) {
      console.log("Session started with ID: " + e.detail.verification_session_id);
    });

    // Successful Event
    verifyFrameRef.current!.addEventListener("aiprise:successful", function (e) {
      console.log("Session with ID " + e.detail.verification_session_id + " was successful.");
    });

    // Continue Event
    verifyFrameRef.current!.addEventListener("aiprise:continue", function (e) {
      console.log("Session with ID " + e.detail.verification_session_id + " was continueed.");
    });

    // Error Event
    verifyFrameRef.current!.addEventListener("aiprise:error", function () {
      console.log("Unable to start session. Check your console for errors.");
    });
  }, []);

  return (
    <div>
      <div style={{ width: "400px", height: "850px" }}>
        <aiprise-frame
          ref={verifyFrameRef}
          template-id="YOUR_TEMPLATE_ID"
          mode="SANDBOX/PRODUCTION"
          callback-url="http://yourcallbackurl.com"
          client-reference-id="SOME_ID_YOU_WANT_TO_ASSOCIATE_WITH_YOUR_REQUEST"
          client-reference-data={JSON.stringify({ some_data: "some_value" })}
          user-data={JSON.stringify({
            first_name: "Your Users First Name",
            middle_name: "Your Users Middle Name",
            last_name: "Your Users Last Name",
            date_of_birth: "YYYY-MM-DD",
            phone_number: "+11234567890",
            email_address: "[email protected]",
            ip_address: "0.0.0.0",
            address: {
              address_street_1: "...",
              address_street_2: "...",
              address_city: "...",
              address_state: "...",
              address_zip_code: "...",
              address_country: "...",
            },
          })}
          icon="YOUR_40X40_LOGO_URL_FOR_ERROR_SCREEN"
          color="YOUR_BRAND_HEX_CODE_FOR_LOADING_SPINNER"
        />
      </div>
    </div>
  );
};