Embedding your knowledge base with JavaScript

Another way to present your help center is to embed it directly into your own website or application using a simple JavaScript snippet. The snippet creates an iframe that displays your help center inside your own page.

There are two things to set up: the embed code on your page, and the embedding origins setting that tells your help center which sites are allowed to load it. Both are required — an embed without the matching origin will show up as an empty area on your page.

Step 1: Allow your website to embed the help center

For security, your help center refuses to load inside a frame on a site you haven’t approved. This stops other people from framing your content and passing it off as their own. Before the embed can appear, add the domain of the page that will host it.

1. Go to your help center’s Settings page.

2. Find the Embedding origins section.

3. Enter the domain of the page where the help center will be embedded (for example www.mycompany.com) and press Enter.

4. Save your settings.

A few notes on what to enter:

• Enter the domain only. Pasting a full URL such as https://www.mycompany.com/support is fine too — the scheme, path and port are ignored, and only www.mycompany.com is stored.

• www.mycompany.com and mycompany.com are different origins. If your site is reachable at both, add both.

• Use a leading dot for a subdomain wildcard. .mycompany.com allows www.mycompany.com, app.mycompany.com and any other subdomain.

• You can add as many origins as you need — staging and production, several brands, or a partner site.

This same setting also controls which sites may load the floating Smart Widget, so if you already use the widget on your website the domain is likely listed already.

Step 2: Insert the embed code

Insert the code snippet below at the exact location on your page where you want the help center to appear.

<div id="hc_embed"></div>
<script>
    var subdomain = 'your_subdomain';
</script>
<script src="//helpcenter.io/js/embed.js"></script>

Replace your_subdomain with the actual subdomain assigned to your help center (for example, mycompany for mycompany.helpcenter.io).

The <div id="hc_embed"></div> element determines where the help center appears on your page. You can position it anywhere and style it with CSS to match your website’s design for a seamless integration.

For example:

#hc_embed {
    width: 100%;
    min-height: 600px;
    border: none;
}

Step 3: For help centers on a custom domain

If your help center is hosted on a custom domain instead of the default *.helpcenter.io subdomain, you’ll need to include an additional configuration option in your embed script. Otherwise, your embedded help center might not work as expected.

Here’s how your script should look:

<div id="hc_embed"></div>
<script>
    var subdomain = 'your_subdomain';

    window._hcEmbedOpts = {
        customDomain: 'help.mycompany.com'
    };
</script>
<script src="//helpcenter.io/js/embed.js"></script>

This customDomain option tells the embed script to load your help center from your own domain (e.g. help.mycompany.com) instead of the default HelpCenter.io domain.

Step 4: Add a preloader (optional)

You can include a preloader or loading animation inside the <div id="hc_embed"></div> element. This will be displayed until the help center fully loads.

Step 5: Use JavaScript-only mode (optional)

If you’d like to disable your default help center URL and use only the embedded version, you can enable the “JS-only embedding” option from your Help Center’s Settings page.

Follow this guide for detailed instructions.

Embedding inside another tool

Sometimes the page holding your help center is itself embedded in something else — a Looker Studio report, a Notion page, an intranet dashboard, or a website builder that puts custom HTML in its own frame. In that case there is a chain of pages between your help center and the browser tab, and every one of them has to be listed in Embedding origins. Listing only the page you can see is the most common reason an embed still fails after the setting is configured.

Common cases:

• Looker Studio / Google Data Studio (URL embed or External Content component): add lookerstudio.google.com and datastudio.google.com. Reports open on either domain depending on the link, so add both.

• Wix (Embed HTML / Custom Code element): Wix serves custom HTML from its own file host, so add that host as well as your own domain. It is your domain with the dots replaced by dashes, followed by .filesusr.com — for www.mycompany.com it is www-mycompany-com.filesusr.com.

• Other builders and dashboards (Squarespace, Notion, intranet portals): many wrap custom HTML in a helper domain of their own the same way. You don’t have to guess it — the browser message in the troubleshooting section below names the exact domain to add.

If your tool isn’t listed here, the troubleshooting step below tells you exactly which domain to add.

Prefer a plain iframe?

You don’t have to use the JavaScript snippet. If you only need the help center on the page and don’t need it to resize itself or sync the page URL, a plain iframe works too:

<iframe src="https://mycompany.helpcenter.io"
        width="100%" height="100%" style="height:100vh;border:0"
        title="Help Center"></iframe>

The Embedding origins setting from Step 1 applies in exactly the same way. The JavaScript snippet is the better option when you want the frame to grow with the content, reflect the current article in your page URL, and keep in-page links working.

Troubleshooting: the embed area is blank

A blank or empty area where the help center should be almost always means the host page isn’t on the Embedding origins list. Your browser will tell you exactly which page it objected to.

1. Open the page with the embed.

2. Open your browser’s developer tools (F12, or right-click and choose Inspect) and select the Console tab.

3. Reload the page and look for a message like this one:

Refused to display 'https://mycompany.helpcenter.io/' in a frame
because an ancestor violates the following Content Security Policy
directive: "frame-ancestors 'self' www.mycompany.com".

The list inside the quotes is what your help center currently allows. Compare it with the address of the page doing the embedding: whichever domain is missing is the one to add in Settings → Embedding origins. If the page is nested inside another tool, check the Application → Frames panel in developer tools to see every page in the chain.

A few other things worth checking:

• The domain matches exactly. mycompany.com does not cover www.mycompany.com. Add both, or use .mycompany.com.

• The help center is published and, if it’s private or password protected, that the reader can access it.

• You saved the settings. Changes take a short while to reach our CDN, so wait a couple of minutes and reload with a hard refresh (Ctrl+Shift+R, or Cmd+Shift+R on a Mac).

You’re all set

Once configured, your help center will appear directly inside your website or app — even as a subdirectory route or behind your own authentication wall, without requiring any SSO setup.

Have fun and reach out to us if you have any questions.