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 mode and template-id are the only required attributes. You can add others as per your requirements.

Basic Usage

import "aiprise-web-sdk";

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

Advanced Usage

Apart from mode and 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 (event will be fired after 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. Note: "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);
    });

    // Business Profile Created (KYB Only)
    verifyButtonRef.current!.addEventListener("aiprise:business-profile", function (e) {
      console.log("Business profile created with ID: " + e.detail.business_profile_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 (e) {
      console.log("Error " + e.detail.error_code);
      // Error Codes:
      // SESSION_FAILED is fired when session creation fails (due to incorrect values, internet or server issues, etc)
      // SESSION_EXPIRED happens when you try to resume a session but the session ID has expired
      // SESSION_COMPLETED happens when you try to resume a session but the session has already been completed by the user
    });
  }, []);

  return (
    <div>
      <aiprise-button
        ref={verifyButtonRef}
        template-id="YOUR_TEMPLATE_ID"
        mode="SANDBOX/PRODUCTION"
        
        callback-url="http://yourcallbackurl.com"
        events-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" })}
        
        ui-options={JSON.stringify({
          id_verification_module: {
            allowed_country_code: "US" // 2-Letter Country Code. Disables all other countries.
          }
        })}
        verification-options={JSON.stringify({
          AML_CONFIG: {
            fuzziness_score: 0.8, // Number
            exact_match: 0.8, // Number
            monitoring: false // Boolean
          }
        })}
        
        // Optional / Only for KYC
        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: "...",
          },
        })}
        
        // Optional / Only for KYC
        additional-info={JSON.stringify([
          {
            additional_info_type: "TYPE_HERE",
            additional_info_data: "DATA_HERE",
          },
          {
            additional_info_type: "TYPE_2_HERE",
            additional_info_data: "DATA_2_HERE",
           },
        ])}
        
        icon="YOUR_40X40_LOGO_URL"
        title="YOUR_BUTTON_TEXT"
        color="YOUR_BRAND_HEX_CODE_WITH_#"
        text-color="BUTTON_TEXT_COLOR_HEX_CODE_WITH_#"
        theme={JSON.stringify({/* THEME OPTIONS */})}
      />
    </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

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.

To customize the verification UI you can pass in the theme options which are documented here.

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 like a button click) and hiding it when the user has filled the entire form.

Just like the button, the mode and template-id are the only required attributes. 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
          mode="SANDBOX/PRODUCTION"
          template-id="YOUR_TEMPLATE_ID"
        />
    </div>
  );
};

Advanced Usage

Similar to the button component, you can pass props here for the callback URL, user data, 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);
    });

    // Business Profile Created (KYB Only)
    verifyFrameRef.current!.addEventListener("aiprise:business-profile", function (e) {
      console.log("Business profile created with ID: " + e.detail.business_profile_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 (e) {
      console.log("Error " + e.detail.error_code);
      // Error Codes:
      // SESSION_FAILED is fired when session creation fails (due to incorrect values, internet or server issues, etc)
      // SESSION_EXPIRED happens when you try to resume a session but the session ID has expired
      // SESSION_COMPLETED happens when you try to resume a session but the session has already been completed by the user
    });
  }, []);

  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"
          events-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" })}
        
          ui-options={JSON.stringify({
            id_verification_module: {
              allowed_country_code: "US" // 2-Letter Country Code. Disables all other countries.
            }
          })}
          verification-options={JSON.stringify({
            AML_CONFIG: {
              fuzziness_score: 0.8, // Number
              exact_match: 0.8, // Number
              monitoring: false // Boolean
            }
          })}
        
          // Optional / Only for KYC
          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: "...",
            },
          })}
          
          // Optional / Only for KYC
          additional-info={JSON.stringify([
            {
              additional_info_type: "TYPE_HERE",
              additional_info_data: "DATA_HERE",
            },
            {
              additional_info_type: "TYPE_2_HERE",
              additional_info_data: "DATA_2_HERE",
             },
          ])}
          
          icon="YOUR_40X40_LOGO_URL_FOR_ERROR_SCREEN"
          theme={JSON.stringify({/* THEME OPTIONS */})}
        />
      </div>
    </div>
  );
};

Resuming Sessions

Each time you click on the <aiprise-button /> component and each time the <aiprise-frame /> component mounts, we create a new session. However in some cases, you may want to resume an old session.

For example you allow the user to go to another tab and come back. In such cases, you can provide us the old session ID and we will resume it directly instead of creating a new one.

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) {
      // Access the session id like this => e.detail.verification_session_id
      // Save the session ID in this step. Give it back to the component to resume.
    });
  
    // Resumed Event
    verifyButtonRef.current!.addEventListener("aiprise:resumed", function (e) {
      console.log("Session resumed with ID: " + e.detail.verification_session_id);
    });
  
    // Data Saved Event
    verifyButtonRef.current!.addEventListener("aiprise:data-saved", function (e) {
      console.log("Session data saved. Data associated with " + e.detail.email_address);
    });

    // Data Restored Event
    verifyButtonRef.current!.addEventListener("aiprise:data-restored", function (e) {
      console.log("Session data restored by verifying OPT. Session ID was " + e.detail.verification_session_id);
    });
  }, []);

  return (
    <div>
      <aiprise-button
        ref={verifyButtonRef}
        mode="SANDBOX/PRODUCTION"
        session-id="THE_ID_OF_THE_SESSION_YOU_WANT_TO_RESUME"
        template-id="YOUR_TEMPLATE_ID" // This will be ignored when resuming but TypeScript requires this so always pass it
      />
    </div>
  );
};

This works the same way for both the button and frame component.