Setting up the API integration

You don't have to connect anything to audit a website - scanning needs no analytics. Connecting lets you choose the friction finder when you set up an audit. It uses UX signals from your analytics to uncover the journeys customers struggle on, with a reason against each step, and the pages on those journeys become the audit.

You connect during the audit set-up, on the API step that appears when you choose the friction finder. Each audit can have one Google Analytics and one Microsoft Clarity connection.

What we read

• Page-level figures from Google Analytics - sessions, entrances, exit rate, engagement rate and engagement time.
• Frustration signals from Clarity - rage clicks, dead clicks, quick backs, scroll depth and script errors.

We never read individual session recordings, never collect personal information about visitors, and never write back to your analytics account.

Step 1 - Find your GA4 Property ID

1. Open Google Analytics and switch to the property you want to connect.
2. Click the gear icon (Admin) in the bottom-left.
3. Open Property Settings.
4. Copy the numeric Property ID at the top - it looks like 123456789. Keep it somewhere; you'll paste it into UXDuty in Step 5.

Step 2 - Create a Google Cloud service account

1. Open console.cloud.google.com.
2. If you don't have a project, create one - any name will do (e.g. "UXDuty integration").
3. From the menu (☰), go to APIs & Services → Library.
4. Search for Google Analytics Data API and click Enable.
5. Go to APIs & Services → Credentials.
6. Click Create Credentials → Service Account.
7. Give it a name (e.g. uxduty-reader) and click Create and Continue.
8. Skip the optional "Grant this service account access to project" and "Grant users access" steps - click Done.

Step 3 - Generate the JSON key

1. From the Credentials page, click into the service account you just created.
2. Open the Keys tab.
3. Click Add Key → Create new key → JSON.
4. Click Create. Your browser will download a JSON file.

Treat that JSON file like a password. Anyone with it can read your analytics. Keep it out of version control and don't paste it into chat tools.

Step 4 - Grant the service account access to your GA4 property

1. Back in Google Analytics, click the gear icon (Admin) again.
2. Open Property Access Management.
3. Click the + in the top-right and choose Add users.
4. For the email, paste the service account's email address. You'll find it in the JSON file under client_email - it looks like uxduty-reader@your-project.iam.gserviceaccount.com.
5. Set the role to Viewer.
6. Untick Notify new users by email - the service account isn't a real person.
7. Click Add.

Step 5 - Paste both into UXDuty

1. In UXDuty, open the API step of a new audit, or the audit's gear icon, then Audit settings and Analytics integrations.
2. Expand Google Analytics.
3. Paste the GA4 Property ID from Step 1 into GA4 Property ID.
4. Open the JSON file in any text editor, copy the entire contents (including the curly braces), and paste them into the Service account JSON field.
5. Click Connect. UXDuty makes a real test call to your property. If it works you'll see Connection verified; if not, the message tells you which step needs revisiting.

Common GA4 connection problems

• "GA4 property not found. Check your Property ID." - the Property ID is wrong. Use the numeric ID from Property Settings (Step 1), not a measurement ID.
• "Permission denied. Make sure the service account has access to this GA4 property." - the service account hasn't been added as a Viewer (Step 4).
• "Invalid service account credentials. Check your JSON key file." - the JSON was pasted incompletely. Copy the whole file, including the curly braces.
• "Connection failed" followed by a message from Google - most often the Google Analytics Data API isn't enabled on the Cloud project the service account belongs to (Step 2).

UXDuty only supports GA4. If you're still on Universal Analytics you can still run audits; the friction finder becomes available once you migrate.

Step 1 - Generate a Clarity API token

1. Open clarity.microsoft.com and switch to the project you want to connect.
2. Go to Settings → Data Export.
3. Click Generate new API token.
4. Give it a recognisable name (e.g. UXDuty) and click Generate.
5. Copy the token immediately. Clarity won't show it to you again - you'd have to generate a new one.

Step 2 - Paste the token into UXDuty

1. In UXDuty, open the API step of a new audit, or the audit's gear icon, then Audit settings and Analytics integrations.
2. Expand Microsoft Clarity.
3. Paste the token into API token.
4. Click Connect. UXDuty verifies the token and shows Connection verified.

The token is scoped to the Clarity project that issued it - connecting another Clarity project just means generating a token in that project too.

Common Clarity connection problems

• "Invalid API token" - check the token under Settings → Data Export, or generate a new one.
• "Daily API limit reached (10 requests/day)" - Clarity limits its API to ten requests a day. Connecting, detecting signals and running an analysis each use some, so try again tomorrow.
• "No data returned" - the Clarity project may not have enough traffic yet.