Wrap Knock links and preserve visitor identity

Use Knock.wrapLink() when sending a visitor from your website or product to a Knock destination.

Wrapping the link attaches Knock's visitor ID to the URL so the session on the Knock destination can be connected to the same person.

The Knock tag must already be installed on the page.

Wrap a Knock link

Use:

window.Knock.wrapLink(url);

For example:

const url = window.Knock.wrapLink(
  'https://start-chat.com/slack...'
);

We recommend using a helper that falls back to the original URL if the Knock tag has not finished loading:

function knockWrapLink(url) {
  if (window.Knock) {
    return window.Knock.wrapLink(url);
  }

  return url;
}

Then use it whenever you send someone to a Knock destination.

Navigate to a Knock link

window.location.href = knockWrapLink(knockSlackUrl);

Open a Knock link in a new tab

window.open(
  knockWrapLink(knockSlackUrl),
  '_blank'
);

Add a wrapped URL to a link

You can also set the wrapped URL on an anchor before the visitor clicks it:

document.getElementById('slack-link').href =
  knockWrapLink(knockSlackUrl);

Which links should I wrap?

Wrap links to Knock destinations.

For example:

• Knock chat links
• Knock Slack links
• Knock meeting links

Do not wrap links to your own application or unrelated third-party destinations.

There is nothing on those destinations that needs to read the Knock visitor ID.

What happens if Knock has not loaded yet?

Unlike other Knock API calls, wrapLink() usually needs to return a URL immediately because your application may be about to navigate somewhere.

That is why the helper returns the original URL when window.Knock is not available:

function knockWrapLink(url) {
  if (window.Knock) {
    return window.Knock.wrapLink(url);
  }

  return url;
}

The link still works.

It simply won't include the Knock visitor ID.

Use identify() and wrapLink() together

For the best continuity, identify the user when your application knows who they are:

knockIdentify({
  email: user.email,
  firstName: user.firstName,
  lastName: user.lastName,
});

Then wrap the URL when sending them to Knock:

window.location.href =
  knockWrapLink(knockSlackUrl);

A complete helper can look like this:

Then:

knockIdentify({
  email: user.email,
  firstName: user.firstName,
  lastName: user.lastName,
});

And when you send the user to Knock:

window.location.href =
  knockWrapLink(knockSlackUrl);

For more information about identifying users, see Identify logged-in users with Knock.

On this page

• Wrap Knock links and preserve visitor identity
• Wrap a Knock link
• Navigate to a Knock link
• Open a Knock link in a new tab
• Add a wrapped URL to a link
• Which links should I wrap?
• What happens if Knock has not loaded yet?
• Use identify() and wrapLink() together