Custom Identity Provider

Custom Identity Provider was created for those who build more advanced integrations that handle user sessions. It allows you to match customer identities in Text with those stored in your service. As a result, your customers will never lose chats they had with your support. What is more, if you also use Text on other platforms (for example, in mobile applications), customer conversations will sync, making the communication even more seamless and natural. From the technical perspective, custom identity is an ID assigned to each customer by our API. Based on that ID, we can match customer data and chat history with a specific person using our services. Custom identity is not customer metadata such as name or email. If you would like to pass one of those, you are probably looking for updating session variables. The Custom Identity Provider routes all of your widget traffic through the Customer Chat API. All requests from such implementation count toward your API usage and fall under the standard API pricing.

Setup

Custom Identity Provider is essentially a singleton function.

// Custom Identity Provider
function () {
    return {
        getToken: ...,
        getFreshToken: ...,
        hasToken: ...,
        invalidate: ...
    }
}

You can define it as a part of the LiveChatWidget object from the tracking code used to install the Chat Widget on your website or from any other place with access to the window.__lc object (in case of more advanced applications). However, it has to be provided before widget initialization.

window.__lc.custom_identity_provider = function () {
    return {
        getToken: ...,
        getFreshToken: ...,
        hasToken: ...,
        invalidate: ...
    }
}

You can also use it with Customer SDK if you build your own chat widget implementation. Pass it through the optional identityProvider parameter of the configuration object.

const customerSDK = CustomerSDK.init({
    licenseId: LICENSE_ID,
    clientId: CLIENT_ID,
    identityProvider: function () {
        return {
            getToken: ...,
            getFreshToken: ...,
            hasToken: ...,
            invalidate: ...
        }
    }
})

Methods

In order to make Custom Identity Provider work, you’ll have to properly implement and provide a set of following methods:

getToken - resolving Chat Widget token. If you want to cache the token, this should return the cached token instead of a fresh request to https://accounts.livechat.com/customer/token endpoint.
getFreshToken - resolving Chat Widget token. This should always make a call for a fresh token from https://accounts.livechat.com/customer/token endpoint.
hasToken - resolving boolean. It determines whether a token has been acquired.
invalidate - resolving nothing. When called, it should remove the current token. There is no need to do anything else as a new token will be requested by getFreshToken afterward.

All of the above will have to be returned in a function assigned to window.__lc.custom_identity_provider. The authorization token to resolve in functions should contain the following properties:

Parameter	Description
`accessToken`	A token you can use to call the Text APIs on behalf of the user (customer).
`entityId`	The ID of the customer.
`expiresIn`	A number in milliseconds specifying how long the `accessToken` will be valid.
`tokenType`	Value: `Bearer`.
`creationDate`	Unix timestamp specifying the time of creation of the token.
`licenseId`	Text license ID.

How to acquire it?

In order to get a Chat Widget token, you need to implement a function that calls the https://accounts.livechat.com/customer/token endpoint. To do so, you can follow customer authorization flows or have a look at our example that uses cookies. The first time you execute this logic, the connection between our customer_id (entity_id) and the identity from your service doesn’t exist yet. Start by creating a new custom identity. Next time you execute this logic, you’ll be able to provide entity_id, and therefore, you will only need to refresh the token. Mind the fact that the data returned from the endpoint is not 1:1 with the token shape described above. You’ll have to make the following adjustments to your token before passing it further:

Rename all the keys from snake_case to camelCase
Add the creationDate and licenseId fields.
Multiply expiresIn by 1000. It’s because we expect expiresIn to be expressed in milliseconds while the endpoint operates in seconds.

Examples

Here are our suggested implementations of Custom Identity Provider. The fetchTextToken() method is used in the examples to acquire the Chat Widget token.

Without caching

If you don’t need to cache the token, the fetching logic shall occur on every refresh of your application page. In such a case, the implementation can be very simple – we only have to ensure the handling of the getToken promise, and resolve other promises.

window.__lc.custom_identity_provider = () => {
  const fetchTextToken = () => {
    // fetch a token from the Text Accounts API here
  };

  let tokenPromise = null;
  const fetchToken = () => {
    tokenPromise = fetchTextToken().then((response) => {
      tokenPromise = null;
      return response;
    });
    return tokenPromise;
  };

  return {
    getToken: () => tokenPromise || fetchToken(),
    getFreshToken: () => tokenPromise || fetchToken(),
    hasToken: () => Promise.resolve(false),
    invalidate: () => Promise.resolve(),
  };
};

With caching

If you care about the number of requests being made in your application, you can unleash the full potential of the Custom Identity Provider.

window.__lc.custom_identity_provider = () => {
  const fetchTextToken = () => {
    // fetch a token from the Text Accounts API here
  };

  const cacheKey = "YOUR_CACHE_KEY";
  let tokenPromise = null;
  let cachedToken = null;

  const isExpired = ({ creationDate, expiresIn }) =>
    Date.now() >= creationDate + expiresIn;

  const token = window.sessionStorage.getItem(cacheKey);
  if (token) {
    cachedToken = JSON.parse(token);
  }

  const getToken = () => {
    if (tokenPromise) {
      return tokenPromise;
    }

    if (cachedToken && !isExpired(cachedToken)) {
      return Promise.resolve(cachedToken);
    }

    return getFreshToken();
  };

  const getFreshToken = () => {
    tokenPromise = fetchTextToken().then(
      (token) => {
        tokenPromise = null;
        window.sessionStorage.setItem(cacheKey, JSON.stringify(token));
        cachedToken = token;
        return token;
      },
      (error) => {
        throw error;
      },
    );
    return tokenPromise;
  };

  const hasToken = () => Promise.resolve(!!cachedToken);

  const invalidate = () => {
    cachedToken = null;
    window.sessionStorage.removeItem(cacheKey);
  };

  return {
    getToken,
    getFreshToken,
    hasToken,
    invalidate,
  };
};

Tutorial

See our tutorial for a full walkthrough of setting up a Custom Identity Provider.

Repository

See the example application presenting the usage of the Custom Identity Provider mechanism.

Getting started

Key concepts

API overview

Authentication

Setup

Methods

Chat Widget token

How to acquire it?

Examples

Without caching

With caching

Tutorial

Repository

​Setup

​Methods

​Chat Widget token

​How to acquire it?

​Examples

​Without caching

​With caching

​Tutorial

​Repository

Setup

Methods

Chat Widget token

How to acquire it?

Examples

Without caching

With caching

Tutorial

Repository