Skip to main content

JavaScript SDK

You can use the Real ID JavaScript SDK for advanced custom use cases to trigger ID checks without relying on the built-in triggers available in the before checkout flow.

The JS SDK lets you to programmatically require ID verification gates at any time on the frontend of your site.

Getting Started​

If you have the before checkout flow enabled and are working with an Online Storefront page in Shopify or WooCommerce, then SDK will be included automatically.

But if you have no automatic verification enabled or are working on a custom page outside of the online store, then you'll need to install the SDK on your site. Include the script tag to install it:

<script
  type="text/javascript"
  src="https://www.idv.link/assets/index.js"
></script>

Then this script tag will load the RealID object into your browser window.

tip

You'll need to use an HTTPS server for a secure connection in order to properly load the assets for the SDK as well as access the customers camera during verification.

Creating an ID verification gate​

Real ID supports two separate modes for prompting ID verification from your customers.

You can simply display the ID check as an element, or you can either override a button or element that requires ID verification, such as a checkout or form submission button.

  • full mode - embed the entire ID verification prompt directly in the current page
  • modal mode - replace the target element with an ID verification button, then after the customer is verified or manually approved, show the original element such as a checkout or form submission button again.

full Mode Example​

// Create a new ID verification wizard
RealID.createFlow({
  // this will display the ID verification wizard immediately on the target.
  target: "#real-id-mount",
  mode: "full",
});

You can initialize a new ID verification prompt by using the RealID.createFlow method. This method accepts a target which will be used to replace the target with the ID verification prompt.

After the customer verifies their ID, then they'll be able to see the target element again.

// Create a new ID verification gate
RealID.createFlow({
  // override the Checkout button until the customer is verified
  target: ".checkout-btn",
  mode: "modal",
});

Real ID will automatically replace all elements with an ID verification prompt.

Shopify and WooCommerce support only

At this time the JS SDK only supports Shopify & WooCommerce, since we can infer your stores settings from these platforms.

Removing the ID verification gate​

You can also remove the ID verification gate by calling RealID.unmount().

This will unmount all Real ID flow instances on your frontend immediately, and will restore the target elements.

// immediately remove the ID gates from the page and restore any hidden elements
RealID.unmount();

Loading in a specific check​

Only for advanced use cases

Real ID JS SDK will automatically create the ID check and associate it with the currently logged in user for you. You typically do not need to use the REST API to create an ID check manually and pass it to the JS SDK.

Passing an ID check manually overrides this behavior, and it's only recommended for advanced use cases like invalidating past approved ID checks on a custom schedule.

By default, the Real ID JS SDK will create an ID check on behalf of the customer. If the customer is logged in, it will automatically pull in their customer ID and will automatically populate their email address and name into the ID check.

Then if the customer returns to this page later, their ID check will be automatically retrieved based on their browser cookies or account details. Find more details about this process here. This helps by making sure the customer only has a single ID check by default.

However, if you need more control - such as expiring IDs or requiring customers to verify again before a specific event, then you can pass a checkId parameter to load a specific ID check.

You can use our REST API to create a check programmatically, which will return the checkId that you can use to pass to the JS SDK options like so:

RealID.createFlow({
  target: "#real-id-mount",
  mode: "full",
  // always load this specific ID check
  checkId: `abc123`,
});
Fallback behavior

If checkId is null or an empty string, then the SDK will fallback to the normal behavior of looking up or creating a new ID check based on the currently logged in customer's information.

However, if the checkId is invalid, then a new ID check will not be created and the customer will be prompted to enter in their email address to load their ID check.

For best results, please be certain that the checkId is a valid ID check token or you safely provide a null or empty string.

Loading the customer's current ID check​

If you are passing the customer's ID to the create ID check REST API endpoint, then you can use WooCommerce meta or Shopify metafields to load the customer's check ID:

Use the check_id stored by Real ID on your customers accounts.

// in a liquid template
RealID.createFlow({
  target: "#real-id-mount",
  mode: "full",
  // always load this specific ID check
  checkId: "{{ customer.metafields.real_id.check_id }}",
});
External database supported

If you store customer accounts on a database outside of Shopify or WooCommerce, then you can use this method to retrieve the customer's ID check token and render their ID check on your site.

Theming​

The JS SDK supports theme customization through the theme parameter, allowing you to override default behaviors and content.

Theme Configuration​

RealID.createFlow({
  target: "#real-id-mount",
  mode: "modal",
  // Changing the verified button to redirect to a specific URL
  theme: {
    verified: {
      button: {
        content: "Continue to Checkout",
        url: "https://yourstore.com/checkout",
      },
    },
    // disabling desktop users from using their desktop camera, and forcing a cross device exchange via a QR code
    camera: {
      desktop: {
        enabled: false,
      },
    },
  },
});

Available Theme Options​

theme.verified.button​

Controls the call-to-action button displayed after successful ID verification.

  • content (string, required): The text displayed on the button
  • url (string, required): The URL to redirect to when the button is clicked

Example:

theme: {
  verified: {
    button: {
      content: "Checkout",
      url: "https://mystore.com/checkout"
    }
  }
}

Default Behavior:

  • If not specified, the button will show platform-specific default text (e.g., "Continue to Checkout" for pre-checkout flows)
  • Without a custom URL, users are redirected to platform-specific default locations (checkout page, order status, etc.)

theme.camera.desktop​

Controls the availability of desktop webcam option during ID verification.

  • enabled (boolean, optional, default: true): Whether to show using a webcam as an option on desktop devices

Example:

theme: {
  camera: {
    desktop: {
      enabled: false; // Hide desktop webcam option, force mobile QR scan
    }
  }
}

Use Cases:

  • Security-conscious environments: Disable desktop cameras for compliance
  • Mobile-first experience: Encourage better photo quality through mobile capture
  • Technical limitations: When desktop webcam quality is insufficient

Behavior:

  • When enabled: true (default): Desktop users see QR code scan, desktop webcam, and manual upload options
  • When enabled: false: Desktop users only see QR code scan and manual upload options
  • Mobile devices are unaffected by this setting

Theme Priority​

Theme settings follow this priority order (highest to lowest):

  1. JS SDK theme parameter - Passed directly to createFlow()
  2. Shop settings theme - Configured in the Real ID app dashboard
  3. Default platform behavior - Built-in fallbacks

This means JS SDK theme options will always override shop-level theme settings.

Complete Example​

RealID.createFlow({
  target: ".checkout-button",
  mode: "modal",
  theme: {
    // Customize the success button
    verified: {
      button: {
        content: "Complete Your Purchase",
        url: "https://mystore.com/checkout?verified=true",
      },
    },
    // Disable desktop webcam for security
    camera: {
      desktop: {
        enabled: false,
      },
    },
  },
});

::: Additional customizations available

We can help add additional theme options and customizations. Please contact us if you need additional configuration or settings.

:::

Frequently Asked Questions​

How do I know if the Real ID JS SDK is available in the current page in Shopify?​

Within your browser's JavaScript console, enter in window.RealID. If the result is undefined, then that means you need to install the JS SDK on that page.

Will already verified repeat customers be verified automatically?​

Yes, the SDK will automatically detect if the customer is logged in and has already verified their ID. Or if they are not logged in, then the SDK will find their prior ID check from the customer's email address when they start the flow.

The same methods to remember repeat verified customers for the before checkout flow are used for this SDK.

Will my theme and rules be applied?​

Yes, the Real ID JS SDK will automatically apply the rules, content and theme you've set up in the settings page of the app.

Can I use this on any website outside of Shopify & WooCommerce?​

No, but that is coming soon. You'll be able to use this JS SDK to implement ID verification gates on any website.

Will this work within a Liquid Snippet in my Shopify Theme?​

Yes, you can write JavaScript within a Liquid Snippet. Depending on if the page you're adding the snippet to is within the Storefront then you can skip the installation step.

Will this work within a Shopify Checkout Extension?​

No, Shopify Checkout Extensions don't allow you to write arbitrary HTML. However, you can use our Shopify app checkout block to require ID verification during or after checkout.

Can I use this on my WordPress site pages?​

Yes, you can add ID verification to any page on your WordPress site, even outside of checkout. Please see our guide here.