Microsoft Clarity is a comprehensive, free behavioral analytics tool designed to give you in-depth insights into user behavior on your website. With Clarity, you can utilize session replays, heatmaps, insights, and the Clarity Copilot feature, which provides intelligent summaries and actionable insights to help you optimize your site more effectively and drive data-driven decisions.
The Clarity NPM package will help you bring Clarity directly to your website.
Add this package as a dependency in your project.
npm install @microsoft/clarity
Then import the library in your code
import Clarity from '@microsoft/clarity';
To activate the Clarity project, Clarity needs to be initialized with the Clarity project ID. To get the Clarity project ID, go to your Clarity project > Settings > Overview
// Make sure to add your actual project id instead of "yourProjectId".
const projectId = "yourProjectId"
Clarity.init(projectId);
-
projectId:
String
(Required)- Description: The ID of the project.
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.
Clarity.identify("custom-id", "custom-session-id", "custom-page-id", "friendly-name"); // only custom-id is required
-
customeId:
string
(Required)- Description: The unique identifier for the customer.
-
customSessionId:
string
(Optional)- Description: A custom session identifier.
-
customPageId:
string
(Optional)- Description: A custom page identifier.
-
friendlyName:
string
(Optional)- Description: A friendly name for the customer.
- Clarity securely hashes the customeId on the client before being sent to Clarity servers.
- For optimal user tracking, the Identify API should be called for each page of the website even if you are not passing a custom-session-id or custom-page-id.
Clarity offers many predefined ways to filter and analyze website data. However, you might want to track elements specific to your site or user experience. With custom tags, you can apply arbitrary tags to your Clarity session.
Clarity.setTag("key", "value");
-
key:
string
(Required)- Description: The key for the tag.
-
value:
string | string[]
(Required)- Description: The value(s) for the tag.
If you prefer to instrument these user actions manually via Clarity APIs, call the event API with the action you'd like to track. When Clarity collects data for this event, it appears with your other Smart events in the Filters, Dashboard, Settings, and Recordings vertical.
Clarity.event("custom-event");
-
eventName:
string
(Required)- Description: The name of the event.
If your project is configured to require cookie consent, Clarity uses a unique first-party cookie to track each user with a browser cookie. If cookie consent is required, you must call the consent API to indicate that you have consent from the user to track them using a cookie.
Clarity.consent(); // default value is set to true
Clarity.consent(false);
-
consent:
boolean
(Optional)- Description: Indicates whether consent is given.
You can use the upgrade API to prioritize specific types of sessions for recording. This is useful if you have sessions with specific types of events (such as clicks) that you want to look at or interactions with specific parts of your website (such as a shopping cart).
Clarity.upgrade("reason");
-
reason:
string
(Required)- Description: The reason for the upgrade.
- Clarity documentation
- Clarity support: clarityms@micrsoft.com
- Clarity Legal Terms
- Clarity Privacy Policy