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">

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 - display the entire ID check prompt in page
  • modal mode - replace the target element with an ID verification button, then after the customer is verified or manually approved, show the 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 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​

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.

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.