Xkit

The xkit Developer Hub

Welcome to the xkit developer hub. You'll find comprehensive guides and documentation to help you start working with xkit as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Self-hosted Catalog

Host the integration catalog yourself

If you want more control over how your Integration Catalog is presented, you can host it on your own. Self-hosting allows you to use your own navigation, and even embed the catalog completely in your website.

🚧

Third-party Cookie Warning

With the advent of new privacy-preserving policies from the major browser vendors that restrict the use of 3rd Party Cookies, you may need to use a custom domain to reliably self-host the Integration Catalog. If you need a custom domain, please Contact Support.

Using HTML

In order to render the Integration Catalog, you need to have the following script available on your webpage:

<script src="https://<your-slug>.xkit.co/xkit-catalog.js"></script>
<script>xkit.ready(function () { xkit.renderCatalogDefault() })</script>

You can safely include that script on every page, it will only do anything if an element with the id xkit-app is present on the webpage, in which case it will render the Integration Catalog within that element.

<div id="xkit-app"></div>

In order to log the user into Xkit, you'll need to provide an Xkit User Token to the catalog, which you can do with the data-token attribute on the html element.

<div id="xkit-app" data-token="your_user_token"></div>

If you are serving the Integration Catalog as a subdirectory, you'll need to include the path that is based on.

<div id="xkit-app" data-path="/integrations"></div>

For a complete list of the customization options available with an HTML-hosted catalog, see Configuring xkit-catalog.js.

Using Javascript

If you're using a (non-React) Javascript framework and you would like to self-host the catalog, you can do so with two function calls.

Installation is the same:

<script src="https://<your-slug>.xkit.co/xkit-catalog.js"></script>

When you have the user's token available (either by backend provisioning or by using a JWT), you'll need to log them in.

await xkit.login("your_user_token")

In your Javascript application, when you want the catalog to be available, call xkit.renderCatalog() with the element you want to render the catalog into. Make sure this element (with ID xkit-catalog in this example) is available in the DOM before calling xkit.renderCatalog.

const $el = document.getElementById("xkit-catalog")
xkit.renderCatalog($el, {
  hideTitle: true
})
<body>
  <!-- ... -->
  <div id="xkit-catalog"></div>
  <!-- ... -->
</body>

When you need to remove the catalog (e.g. because the user has navigated away from the page where it exists in your app) call the unmountCatalog function:

const $el = document.getElementById("xkit-catalog")
xkit.unmountCatalog($el)

Using React

If you're already using React on your web app and you want to include the Integration Catalog, you can do so.

The entire Integration Catalog is exported as a single, self-contained React component (using React 16.9).

🚧

React version mismatch

If you use the React component directly, make sure you're using the same version of React (16.9), otherwise you may get an error due to the versions not matching.

First, install the Catalog:

npm install @xkit-co/xkit-catalog.js

Then create your instance of Xkit and pass it to the Catalog component

import * as React from 'react'
import * as ReactDOM from 'react-dom'
import { App as XkitCatalog, createXkit } from '@xkit-co/xkit-catalog.js'

const xkit = createXkit("<your-slug>.xkit.co")

function MyApp () {
  return <XkitCatalog xkit={xkit} />
}

The Integration Catalog uses React Router, so if you're already using React Router, you should disable it to avoid conflicts by setting the inheritRouter prop to true.

If you're not using React Router, you may want to adjust the routerType to use what works best for your app.

Next.js

If you're using Next.js, take a look at our sample Next.js app or our blog post to see how to use the React component with Server-side Rendering.

Configuring the Catalog

See the configuring xkit-catalog.js reference for more details on the available options.

Updated a day ago

Self-hosted Catalog


Host the integration catalog yourself

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.