Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Microsoft Clarity to Fondoo

Live5 min readUpdated

Microsoft Clarity records sessions and builds heatmaps of how people use your site. Fondoo can add the Clarity tag to your published pages and, if you add a Data Export token, let your agent pull recent Clarity dashboard numbers. Clarity has no server-side event API, so Fondoo cannot send events to it.

What Fondoo can do with it

1. The browser tag (public, not a secret). Your Clarity project ID is saved with configure_site_pixels. Fondoo injects the tag from https://www.clarity.ms/tag/<projectId> on the next publish. Previews do not get the tag. Recordings and heatmaps come from this tag and are viewed in Clarity itself.

2. The server connector. Saved with add_connection_key. It has one action, run through connector_action:

  • reports.query (read): export dashboard insights for the last 1, 2 or 3 days, broken down by up to 3 dimensions. Allowed dimensions: Browser, Device, Country/Region, OS, Source, Medium, Campaign, Channel, URL. At most 1,000 rows, with no paging. Needs apiToken.

Each report uses 1 of Clarity's 10 export requests per project per day. Fondoo cannot change Clarity settings, add custom events or tags, or watch recordings. No action needs owner approval. Agents need the analytics:read scope (an owner key also works). Deleting the connection needs owner approval.

Before you start

  • Clarity is free, with no traffic limits or paid tier (FAQ).
  • Sign up at clarity.microsoft.com, click New project, enter the name and website, then Add new project (getting started). The creator becomes the project admin.
  • Only a project admin can create Data Export tokens.
  • Microsoft says Clarity must not be used on sites or apps aimed at people under 18 (setup).

Step by step: get your credentials

Project ID (projectId, required)

  1. Open your project in Clarity and go to Settings → Overview. Microsoft's docs say the Project ID is shown there (getting started).
  2. Or go to Settings → Setup → Install manually → Get tracking code and find clarity.ms/tag/ in the code. The short ID after it (for example abc123xyz0) is your project ID.
  3. Do not paste the whole tracking code into Fondoo; Fondoo writes its own.

The ID goes into both configure_site_pixels and the connector. Clarity does not document the ID format; Fondoo expects 6 to 20 lowercase letters and digits. This may differ for your account.

Data Export API token (apiToken, optional, for reports)

  1. In the same project go to Settings → Data Export → Generate new API token (Data Export API).
  2. Name it, for example fondoo-reports. Names are 4 to 32 characters: letters, digits, -, _ and ., with no spaces. Each name must be unique in the project.
  3. Copy the token and keep it safe. It works only for this project.

There are no scopes to choose. The token can only read export data.

Connect it in Fondoo

a. In the dashboard. Go to Connections → Connect a tool. Type "Clarity" in Find a tool. On the Microsoft Clarity card click Use a key, then Open secure key entry. Fill in projectId, and apiToken if you want reports. Click Save connection securely. The page expires after 15 minutes and works once.

The dashboard has no screen for the browser tag; use your agent or REST.

b. By asking your agent. Example prompt: "Add my Clarity project abc123xyz0 to my site and send me a secure link for the Clarity Data Export token."

The agent calls:

configure_site_pixels({siteId, clarity: {projectId: "abc123xyz0"}})
add_connection_key({provider: "clarity", siteId})

The second call returns a one-use securePasteUrl; never paste the token into chat. Then publish_site injects the tag.

REST: the same calls are POST /v1/ops/configure_site_pixels and POST /v1/ops/add_connection_key, with the call input as the JSON body:

curl -X POST https://api.getfondoo.com/v1/ops/add_connection_key \
  -H "Authorization: Bearer $FONDOO_API_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"clarity","siteId":"YOUR-SITE-ID"}'

Consent. requireConsentForPixels defaults to false, because Fondoo has no per-site region setting. When it is on, no tag loads until your banner calls window.fondooConsent.grant(). Global Privacy Control is always honored. Since 31 October 2025 Clarity needs a consent signal for visitors from the EEA, UK and Switzerland for full functionality, and sets no cookies for them until it gets one (consent mode). Fondoo's consent switch only decides whether the tag loads. It does not pass a signal to Clarity's Consent API, so those sessions may stay in no-cookie mode.

Test that it works

  1. Run test_connection({connectionId}). Fondoo does not spend one of your 10 daily requests on a test. It checks the format locally only:
    • No token: status limited, reports unavailable.
    • Token present: status connected, with reports.query still unknown until the first report.
    • If the token carries an expiry date that has passed, status invalid. Clarity does not document an expiry, so this may differ for your account.
  2. Publish your site, visit it, and check Clarity's live view. Microsoft also suggests checking for requests to clarity.ms/collect in your browser's Network tab.
  3. Run one report: connector_action({connectionId, action: "reports.query", input: {numOfDays: 1, dimensions: ["Device"]}}).

Troubleshooting

  • "Credential fields do not match the connector manifest": the project ID has capitals or extra text, or the token is not a full three-part token. Copy them again.
  • "Clarity reports need the Data Export apiToken credential": add the token with rotate_connection_key and re-enter both fields.
  • Report fails with 401 or 403: the token is wrong, revoked or for another project. Generate a new one.
  • Report fails with 429: you used all 10 requests for the project today. Try again the next day.
  • "numOfDays must be 1, 2 or 3" or "Unsupported Clarity dimension": use only the values listed above, spelled exactly.
  • No recordings: the site was not republished, consent was not granted, or the visitor has Global Privacy Control turned on.

Limits, data and security

  • Data Export: 10 requests per project per day, the last 1 to 3 days only, up to 3 dimensions, up to 1,000 rows with no paging, results in UTC.
  • Clarity masks sensitive text on your pages by default.
  • Credentials are encrypted in Fondoo's connector vault. list_connections shows only a masked value. A rotation reminder is due after 90 days unless you set rotateAfter.
  • To rotate, run rotate_connection_key({connectionId}) and re-enter every field. Microsoft advises replacing tokens when someone with access leaves the project.
  • To disconnect, run delete_connection (needs owner approval). This does not revoke the token; remove it under Settings → Data Export in Clarity.
  • To remove the tag, call configure_site_pixels({siteId, clarity: null}) and publish again.
  • This connector does not use webhooks.