Setting up the API integration

You don't have to connect anything to use UXDuty - manually defined URLs work for most teams. But once you connect, UXDuty surfaces the high-traffic and high-friction routes automatically and ranks suggested scans by how many real customers are exposed.

What we read

• Aggregated journey paths - the routes visitors take, in order.
• Frustration signals - rage clicks, dead clicks, quick-back rates, error sessions (Clarity).
• Engagement-time and session-duration aggregates.

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 project you want to connect, then Integrations.
2. Choose Google Analytics.
3. Paste the GA4 Property ID from Step 1.
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 Save. UXDuty will verify the connection by making a test call. If it works, you'll see Connected; if not, the error message will tell you which step needs revisiting.

Common GA4 connection problems

• "Property not found" - the Property ID is wrong, or the service account hasn't been added as a Viewer in Step 4.
• "API not enabled" - the Google Analytics Data API isn't enabled on the Cloud project the service account belongs to (Step 2, point 4).
• "Universal Analytics property" - UXDuty only supports GA4. If you're still on Universal Analytics, the manual-URL method is the path forward until 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 project, then Integrations.
2. Choose Microsoft Clarity.
3. Paste the API token.
4. Click Save. UXDuty will verify the connection and show Connected.

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