Link user CRMs

Connect to your users' CRMs with our Javascript SDK

To connect your application to your users' CRMs you'll use our Javascript SDK called CRM Link.

CRM Link will allow your users to select their CRM, authorize your access to it, and configure the integration to match their CRM's unique setup.

Once installed, the end user experience for CRM Link will be similar to the below videos.

Authorizing access to the CRM

Authorize Salesforce access with CRM Link

Configuring the CRM integration

Configure CRM integration with CRM Link

Installation & Setup

Install crm-link.js

With React

npm

npm install @xkit-co/crm-link.js

yarn

yarn add @xkit-co/crm-link.js

Usage example

import linkCRM from '@xkit-co/crm-link.js'

const handleClick = async () => {
  // Call your backend route to fetch a context token, see the next section
  const { token } = await fetch('/xkit/token')
  try {
    await linkCRM('example.xkit.co', token, { connectionID: 'context-id' })
    // CRM linked successfully
  } catch (error) {
    // CRM link failed, display an error to the user
  }
}

export default function App() {
  return (
    <button onClick={handleClick}>
      Connect CRM
    </button>
  )
}

With other web frameworks

You will need to add react and react-dom along with @xkit-co/crm-link.js.

From our testing, this adds no more than 45 KB to your final browser bundle.

npm

npm install react react-dom @xkit-co/crm-link.js

yarn

yarn add react react-dom @xkit-co/crm-link.js

Usage example

The process is similar to the example above for React, but where you call linkCRM might change depending on your framework.

The example that follows is for Vue:

<template>
  <button @click="handleClick">Connect CRM</button>
</template>

<script>
import linkCRM from '@xkit-co/crm-link.js'

export default {
  name: 'App',
  methods: {
    handleClick: async () => {
      // Call your backend route to fetch a context token, see the next section
      const { token } = await fetch('/xkit/token')
      try {
        await linkCRM('example.xkit.co', token, { connectionID: 'context-id' })
        // CRM linked successfully
      } catch (error) {
        // CRM link failed, display an error to the user
      }
    }
  }
}
</script>

<style></style>

Without a web framework

You can use the browser script hosted through any public npm CDN. The example that follows uses UNPKG.

Within your document's <head>:

<script src="https://unpkg.com/@xkit-co/crm-link.js@^2/dist/browser.js"></script>
<script>
  const handleClick = async () => {
    // Call your backend route to fetch a context token, see the next section
    const { token } = await fetch('/xkit/token')
    try {
      await linkCRM('example.xkit.co', token, { connectionID: 'context-id' })
      // CRM linked successfully
    } catch (error) {
      // CRM link failed, display an error to the user
    }
  }
</script>

Within your document's <body>:

<button onclick="handleClick()">Connect CRM</button>

To use CRM Link, you'll need to pass three arguments to linkCRM:

  1. Your project domain (example.xkit.co in the usage examples above)
  2. Your user's Xkit Context Token
  3. An object with the connectionID property set to the context ID

Project Domain

When you get access to Xkit, you'll be assigned a project subdomain, something like your-company.xkit.co.

This is your Xkit Project Domain and is used when your end users interact with Xkit.

Your Project Domain can be viewed and edited in the Project Subdomain field on the settings page.

Project Subdomain field in Xkit settings

To use a custom domain, for example integrations.your-company.com, follow the custom domain documentation.

Context ID and Token

In order for Xkit to know who your user is and link their authorization from their CRM, you need to create a Context Token for them.

A Context Token tells Xkit that the user has been authenticated by your app and is authorized to link a CRM.

All that you need to supply to create a Context Token is the Context ID. This is the ID of the entity for whom the CRM is being linked. Depending on your architecture, you may want to link CRMs for entire companies or projects - however you set it up is entirely up to you, all Xkit needs is an ID that is unique within your application.

To get started with using CRM Link in a fashion that is simple, we re-use this Context ID as the value for the connectionID option in the usage examples above. However, you are not restricted to this convention and you can use other values for the connectionID option. Refer to our guide on specifying connection IDs to learn more.

Let us use now use this Context ID to obtain a Context Token. In the examples above, there is a line similar to:

// Call your backend route to fetch a context token
const { token } = await fetch('/xkit/token')

Here's an example backend route which matches the examples above.

It shows an an Express/Node.js app where the req object has a company property representing the company that is currently logged into your app. The req.company.id property is used as the Context ID here.

import axios from 'axios'

// The route matching the `fetch` from the front-end
app.post('/xkit/token', async (req, res) => {
  const { access_token } = await axios({
    url: 'https://app.xkit.co/api/v1/platform/contexts',
    method: 'post',
    auth: {
      username: XKIT_PUBLISHABLE_KEY,
      password: XKIT_SECRET_KEY
    },
    data: {
      // Using the current company ID as the CRM's "context"
      context: {
        external_id: req.company.id,
        // Optional friendly name
        external_name: req.company.name,
      }
    }
  })

  res.json({ token: access_token })
})

XKIT_PUBLISHABLE_KEY and XKIT_SECRET_KEY in the example above refer to an API Key set obtained from the Xkit Developer Portal. Refer to Generating an API Key.

Allow web origins

In order to protect your users from malicious actors, Xkit uses CORS to prevent usage of CRM Link on websites you have not approved.

The first time you load a webpage with CRM Link installed, it will fail with a CORS error in the console.

To fix this error, go to the Web Origins Settings and toggle the "Allow" switch for your attempted origin.

You can also add origins that you expect to use in the future here.

Web Origins Settings

Launch and configure

You've now installed CRM Link.

If you haven't set up any CRMs to link to, trying to link will throw an error.

The third argument to linkCRM is an object for specifying options in the above examples. When you set up how you'll access CRM data using the Universal CRM API, you'll control how users configure their CRM integration by updating this object.

To further customize how CRM Link is launched, take a look at Customizing CRM Link. That is an advanced guide however, so we recommend reading it after you've gone through the rest of the documentation.

Up next

Universal CRM API

Read and write data in your users' CRMs

Read more ▶

Ready to build your CRM app?

Integrate every CRM with one build, request access to get started.