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")

Visit Clarity

Case studies

Demo

Sign in

Blog

Benchmarks