Embedding a Component

Embedding Components requires two steps. First, generate a Component URL from Check’s API and embed that URL into an app using the Component SDK. Each page reload requires a new Component URL to be generated for security purposes.

The following steps will embed the Component in a div. The div can be placed in a sidebar, a modal, or directly on your app’s page. Highlighted in the Check Components Overview are different design patterns you can follow for embedding a Component.

1. Generate a Component URL

Make a POST request to the Component endpoint (the components reference lists them all) to generate a Component URL. For this example, we’re generating a Company’s Tax Setup Component. This should be a server-side request.

/companies/{company_id}/components/tax_setup

This endpoint will return a URL that you will embed in your app.

2. Embed the Component URL (example in React v16.8+)

a) Create a function called importScript().

const importScript = (resourceUrl) => {
 useEffect(() => {
   const script = document.createElement('script');
   script.src = resourceUrl;
   script.async = true;
   document.body.appendChild(script);
   return () => {
     document.body.removeChild(script);
   };
 }, [resourceUrl]);
};

export default importScript;

b) Import the Component SDK via the importScript() in your app.js or index.js.

importScript('https://cdn.checkhq.com/component-initialize.js');

📘

Alternative way to import Component SDK

Instead of steps a) and b), you can alternatively embed the SDK as a script tag directly in HTML.

<script src=”https://cdn.checkhq.com/component-initialize.js” />

c) Create a function to load the Component. In this example case, we’ll use the Company Tax Setup Component.

const loadComponent = (componentLink, componentDivId) => {
  try {
    const handler = window.CheckComponent.create({
      link: componentLink,
      onEvent: (event, data) => {
        // handle Check Component events
      },
    });
    handler.open();
    const componentElement = document.getElementById(
      'check-component-embedded-div',
    );
    if (componentElement) {
      const componentHolder = document.getElementById(componentDivId);
      componentHolder.appendChild(componentElement);
    }
  } catch (err) {
    // handle error
  }
};

❗️

Remember to close the Component handler

It's important to close the handler once the user finishes using a Component (i.e. when closing a modal containing the Component). Run the following function handler.close() to remove it from the DOM. This will avoid the Component being cached on the page which may result in it being loaded again at the next call to handler.open().

📘

TypeScript Note

If you are using TypeScript, whenever you reference the CheckComponent object from the window object, we recommend adding a //@ts-ignore comment above that line (view the example below). This suppresses the ‘property does not exist’ error that your development environment may report because the CheckComponent object will only be added to the window object at runtime.

// @ts-ignore
const handler = window.CheckComponent.create({
  link: componentLink,
  onEvent: (event, data) => {},
});

d) Render the Component by specifying the ID of the div you want your Component embedded in. In this example, we use: my_component_holder, but you can name it whatever you want.

useEffect(() => {
   loadComponent(componentLink, 'my_component_holder');
 }, []);

 return (
   <div>
     <div id="my_component_holder" />
   </div>
 );

🚧

Ensure component links are only initialized once

Certain web frameworks, including React/Next, can make it easy to accidentally initialize the component link multiple times. This can potentially lead to unexpected behavior where a session is expired prematurely.

If you run into this behavior, evaluate your initialization mechanism and put guardrails in place to ensure CheckComponent.create is only called once for a given component link, e.g. by storing and monitoring a loaded variable.

Check Components SDK

The Check Components SDK is hosted here:

https://cdn.checkhq.com/component-initialize.js

The SDK gives you access to the CheckComponent object which can create an API handler object.

CheckComponent.create() Parameters

Handler API

Content Security Policy

Components render in an iframe served from components.checkhq.com. If the page that embeds a component sets a Content Security Policy, its frame-src directive must allow that host:

Content-Security-Policy: frame-src https://components.checkhq.com

If the policy blocks the host, the browser refuses to load the iframe and the embed never appears, with no error in the page. Nothing reaches Check's servers, so the failure shows up in no Check log and fires no SDK event. To confirm a block, open the browser console: the browser reports a CSP violation naming the blocked URL.

Embedding without the SDK

If you place the Component URL in your own <iframe> instead of using the SDK, grant the permissions the SDK grants for you:

<iframe src="{returned_component_link}" allow="clipboard-write; fullscreen; camera; microphone"></iframe>

clipboard-write lets Copy buttons work and fullscreen lets PDFs display in Chrome. camera and microphone matter only for links minted with identity verification enabled, where the filing authorization step runs a Persona liveness check. The SDK adds them for those links automatically.

Appearance settings go on the URL as query parameters. See Customizing Components.