Identify logged-in users with Knock AI

Use Knock.identify() to tell Knock who a visitor is once your product knows their identity.

This is typically done after a user signs up, logs in, or when a page loads for an already logged-in user.

The Knock tag must already be installed on your product.

Identify a user

Call Knock.identify() with the information you know about the user.

window.Knock.identify({
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
});

Because the Knock tag loads asynchronously, window.Knock may not exist yet when your code runs.

We recommend using the following helper:

function knockIdentify(traits) {
  if (window.Knock) {
    window.Knock.identify(traits);
  } else {
    window.addEventListener(
      'knock:ready',
      () => window.Knock.identify(traits),
      { once: true }
    );
  }
}

Then identify the user once you know who they are:

knockIdentify({
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
});

What information can I send?

You can send information you already know about the user.

email is the most valuable single field because it ties the session to a person.

For example:

knockIdentify({
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  company: 'Acme',
  plan: 'pro',
});

You can also include additional traits that are useful for your implementation.

When should I call identify()?

Calling identify() more than once is fine. Later calls can add information you now know about the user.

Why use the knock:ready event?

The Knock tag loads asynchronously.

This means your application code may run before window.Knock is available.

The Knock tag fires the knock:ready event when its API becomes available:

window.addEventListener(
  'knock:ready',
  () => window.Knock.identify({
    email: 'jane@example.com',
  }),
  { once: true }
);

Using { once: true } removes the listener after it fires.

The knockIdentify() helper handles both situations for you:

• If Knock is already available, it calls identify() immediately.
• If Knock is still loading, it waits for knock:ready.

Example: identify a user after signup

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

Example: identify an existing logged-in user

If your application already has an authenticated user when the page loads, identify them when your application initializes:

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

Once the user is identified, you can also use Knock.wrapLink() when sending them to a Knock destination to carry the Knock visitor ID with them.

See Wrap Knock links and preserve visitor identity.

On this page

• Identify logged-in users with Knock AI
• Identify a user
• What information can I send?
• When should I call identify()?
• Why use the knock:ready event?
• Example: identify a user after signup
• Example: identify an existing logged-in user