Partager via

Identify API

  • Article

Customize your identifiers

Custom Identifiers are informational data values about site visitors that are sent to Clarity by your client-side code over its Identify API. They include custom-id, custom-session-id, and custom-page-id and can help you customize the features on your site that requires it.

Key-value pairs are used to transmit this data to Clarity servers. A custom-id identifies value sent to Clarity, retrieves user information from Clarity, and correlate collected data relevant to the ID.

Customizing Custom ID

Clarity automatically generates various types of identifiers needed for its normal functioning. These identifiers aren't consistent across browsers and devices. If a custom-id is set, you can view user journey across devices.

Example: If a user visits your site through mobile and desktop, by default, Clarity considers the sessions as two different users. Providing a custom-id such as an email, can help you view the user journey across browsers and devices.

Similarly, you can also customize custom-session-id and custom-page-id.

API Call

User data is attributed to a custom-id.

Syntax Parameters Required? Returns
window.clarity("identify", "custom-id", "custom-session-id", "custom-page-id", "friendly-name") Strings "custom-id": Yes,
"custom-session-id": No,
"custom-page-id": No,
"friendly-name": No		 Promise <{ id: hash(email), session, page, userHint }>

Note

  • Clarity securely hashes the custom-id on the client before being sent to Clarity servers.
  • For an optimal user tracking, the Identify API should be called for each page of the website even though you are not passing a custom-session-id or custom-page-id.

Example with friendly-name

// window.clarity("identify", "monakane@contoso.com")
// window.clarity("identify", "monakane@contoso.com", "custom-session-id")
window.clarity("identify", "monakane@contoso.com", "custom-session-123", "custom-page-123", "Mona")

//Returns
Promise <{
   id: "custom-id-123"
   session: "custom-session-123",
   page: "custom-page-123",
   userHint: "Mona"
}>

Example without friendly-name

window.clarity("identify", "monakane@contoso.com", "custom-session-123", "custom-page-123")

//Returns
Promise <{
   id: "custom-id-123"
   session: "custom-session-123", 
   page: "custom-page-123",
   userHint: "Mo******************"
}>

Using Custom IDs

You can filter dashboard, session recordings, and heatmaps to a specific custom-id using the custom filters.

Custom IDs in filters.

Storing and managing Custom IDs

Clarity doesn't store custom identifier as a plain text. Instead, the custom ID is hashed on the client before being sent to the servers. When you filter on a specific Custom user ID, Clarity hashes the input and matches it against the data to retrieve the right sessions.

Example: when you send window.clarity("identify", "monakane@contoso.com", "custom-session-123", "custom-page-123"), the custom ID monakane@contoso.com is hashed and is stored on Clarity servers.

If you search for a session with id: monakane@contoso.com, Clarity hashes the search, match the hashes with the existing data and displays the sessions related to this hash.

Note

For optimal user tracking, Identify API should only be used for authenticated users and not for guest users.

Sending multiple custom-page-ids for a given user

Use the relevant custom-page-id when calling the API for each website page.

Example:

If your website has a homepage and a product page:

When you load the homepage, call the API using the home-page-id.

window.clarity("identify", "monakane@contoso.com", "custom-session-id", "home-page-id", "Mona")

Similarly, when you load the product page, call the API using the product-page-id.

window.clarity("identify", "monakane@contoso.com", "custom-session-id", "product-page-id", "Mona")

Visit Clarity

Case studies

Demo

Sign in

Blog

Benchmarks