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 Working with Check Components guide are different design patterns you can follow for embedding a Component.

1. Generate a Component URL

Make a POST request to the Component endpoint (full list here) 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

Live Example

Want a live example? You can play around with Components in our Codepen Demo.