Clarity client API
You can quickly get started with Clarity without coding but by interacting with the Clarity client API. This API can help you access advanced features as described in this reference. Access these features by adding the following calls to Clarity APIs to the HTML or JavaScript of your webpage.
Note
Your Clarity ID serves as your API key. No other client API key is necessary, and there is no cost for using Clarity client APIs.
JavaScript APIs
| Purpose | Syntax | Parameters | Required? |
|---|---|---|---|
| Cookie consent | window.clarity("consent") |
String | Yes |
| Custom identifiers | 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 |
| Custom tags | window.clarity("set", <key>, <value>) |
<key>: string, <value>: string or an array of strings |
Yes |
| Events | window.clarity("event", <value>) |
<value>: string of the event name |
<value>: Yes |
HTML APIs
| Purpose | Syntax | Parameters | Required? |
|---|---|---|---|
| Mask content | data-clarity-mask="true" |
Boolean | Yes |
| Unmask content | data-clarity-unmask="true" |
Boolean | Yes |
API Reference
Specify if cookies should be set
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. Otherwise, Clarity gives each page a unique ID instead of a cookie when cookie consent is required. Clarity automatically sets the first-party cookie by default, and you don't need to call this API.
| Syntax | Parameters | Required? |
|---|---|---|
window.clarity("consent") |
String | Yes |
Example
In this example, a consentGranted event is fired when the user accepts cookies:
window.addEventListener("consentGranted", () => window.clarity('consent'));
When the consent argument is passed to clarity, cookies are set.
Tip
Learn more about how to manage cookie consent on Clarity.
Customize your identifiers
Custom Identifiers are informational data values about site visitors that your client-side code sends to Clarity 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. Learn more on custom identifiers.
Add custom tags
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.
To use custom tags, pass the set argument along with a key-value pair to define a tag in your JavaScript. When Clarity collects data for that tag, it appears in the Filters options.
| Syntax | Parameters | Required? |
|---|---|---|
window.clarity ("set", "key", "value") |
"key": string,"value": string or an array of strings |
Yes |
Note
You can call this API multiple times. There is no limit to the number of custom tags you can have.
Examples
window.clarity("set", "experiment", "experiment1")
window.clarity("set", "flight", ["flight1", "flight2"])
Note: The last call has the same effect as:
window.clarity("set", "flight", "flight1")
window.clarity("set", "flight", "flight2")
Tip
Learn more about Clarity's filtering options and custom tags.
Add custom events
Clarity offers no-code smart events, which automatically surface key user actions. Refer to Smart events to learn how to view, create, and customize new smart events completely code free.
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.
Note
You can call this API multiple times per page. Each event is logged individually and can be filtered, viewed in all the verticals.
Example
window.clarity("event", "newsletterSignup")
Mask your site content
By default, your users' sensitive content is masked. We classify all input box content, numbers, and email addresses as sensitive content. Masked content isn't uploaded to Clarity.
If you want more control over which content on your site is masked, you can mask content using the Clarity website or add the data-clarity-mask property to HTML elements on your site.
Note
Setting data-clarity-mask to false has no effect. To unmask content, use data-clarity-unmask.
| Syntax | Parameters | Required? |
|---|---|---|
data-clarity-mask="true" |
Boolean | Yes |
Example
<form action="" method="get" data-clarity-mask="true">
<label for="GET-name">User Name:</label>
<input id="GET-name" type="text" name="name">
<input type="submit" value="Submit">
</form>
Unmask your site content
Suppose you want to ensure that specific data items are sent to Clarity. In that case, you can unmask them by using data-clarity-unmask.
Note
Setting data-clarity-unmask to false has no effect. To mask content, use data-clarity-mask.
| Syntax | Parameters | Required? |
|---|---|---|
data-clarity-unmask="true" |
Boolean | Yes |
Example
<article class="Movie Review" data-clarity-unmask="true">
<header>
<h2>Star Wars</h2>
</header>
<section>
<p>A classic!</p>
</section>
</article>
Prioritize specific sessions for recording
Clarity keeps up to 100,000 session recordings per project per day. If your project's total volume of sessions exceeds the maximum daily limit, based on your traffic patterns, Clarity starts sampling the recordings it keeps. For example, if your site gets 200,000 sessions in a day, Clarity keeps every other recording.
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).
| Syntax | Parameters | Required? |
|---|---|---|
window.clarity("upgrade", <upgrade reason>) |
Strings | "upgrade": Yes, <upgrade reason>: Yes |
Example
window.clarity("upgrade", "button click")