Add `track` and click auto-tracking to intent client #26

solastley · 2025-09-22T00:36:27Z

This PR adds the track method to the Unify Intent Client which will leverage the new Track API to allow for the logging of custom events and properties for use within Unify.

See the updated README for an in-depth explanation of the new methods.

…racking

aaug1-unify · 2025-09-22T01:07:52Z

src/client/agent/unify-intent-agent.ts

  private _autoPage: boolean;
  private _autoIdentify: boolean;
-  private _historyMonitored: boolean;
+  private _autoTrackOptions?: AutoTrackOptions;


private field isn't referenced in the code, not sure if that's intended

I think rn using this._intentContext.clientConfig.autoTrackOptions

oh good catch that would actually cause a bug

aaug1-unify · 2025-09-22T01:21:08Z

src/client/agent/utils.ts

+    return false;
+
+  return true;
+}


I think there is a <fieldset disabled> that might be worth considering if we are excluding disabled things

samwaterbury

Last thing: We are also changing the header we use to pass the write key to the API. Previously, this was done using a basic auth encoding where the username was the write key and the password was empty, i.e.:

Authorization: Basic {base64(writeKey + ':')}

But now it's just X-Write-Key:

X-Write-Key: {writeKey}

The reasoning is that:

This mirrors our use of X-Api-Key in other public APIs and also makes the distinction a lot clearer
It should be easier for people to construct the header manually when not using a client library

So I think we should change it in this update as well. Here's an example request for reference:

curl -i -X POST https://api.unifyintent.com/analytics/v1/track \
    -H "Content-Type: application/json" \
    -H "x-write-key: wk_abc_def123" \
    -H "Origin: https://unifygtm.com" \
    -d '{
        "type": "track",
        "visitorId": "2a51f825-598b-442a-9493-cafc6a194e92",
        "sessionId": "3d570f4a-48a5-4292-910f-7a53a2d0f081",
        "timestamp": "2025-09-22T17:55:00Z",
        "sentAt": "2025-09-22T17:55:00Z",
        "context": {
            "ip": "209.247.156.154"
        },
        "name": "Clicked a big red button",
        "properties": {
            "reason": "It was there"
        }
    }'

samwaterbury · 2025-09-22T01:51:55Z

README.md


-> [!NOTE]
-> See [@unifygtm/intent-react](https://www.npmjs.com/package/@unifygtm/intent-react) if you are using React.
+**NOTE:**: See [@unifygtm/intent-react](https://www.npmjs.com/package/@unifygtm/intent-react) if you are using React.


Suggested change

**NOTE:**: See [@unifygtm/intent-react](https://www.npmjs.com/package/@unifygtm/intent-react) if you are using React.

**NOTE:** See [@unifygtm/intent-react](https://www.npmjs.com/package/@unifygtm/intent-react) if you are using React.

samwaterbury · 2025-09-22T18:06:44Z

README.md

+1. Custom HTML data attributes (see [here](#html-data-attributes))
+2. Manually via the client `track` method (see [here](#manual-tracking))
+3. Automatically with CSS selectors (see [here](#automatic-tracking))


I'm wondering if this is the right order of recommendation or whether it should be:

The track method

Automatically with CSS selectors

HTML data attributes

The reason is that it seems like using the track method is the most intuitive (because of how closely it mirrors other tools that provide the same method) and can be done one-off or incrementally; CSS selectors seems like the next simplest and most scalable approach; and HTML data attributes seems like the most advanced and requires the most effort.

samwaterbury · 2025-09-22T18:08:33Z

package.json

    "build:browser:s3:staging": "pnpm build:browser && aws s3 cp ./dist/js/browser/index.min.js s3://unifygtm-public/tag/v1/script-staging.js",
    "build:browser:s3:testing": "pnpm build:browser && aws s3 cp ./dist/js/browser/index.min.js s3://unifygtm-public/tag/v1/script-testing.js",
-    "generate": "pnpm openapi-typescript '../unify/api/tsp-output/@typespec/openapi3/openapi.UnifyAnalyticsApi.yaml' -o './src/spec.ts'",
+    "generate": "pnpm openapi-typescript '../unify/api/spec/tsp-output/@typespec/openapi3/openapi.UnifyAnalyticsApi.json' -o './src/spec.ts'",


If you prefer, you can actually now also use the URL (finally got around to hosting it properly):

https://unifyintent.com/analytics/v1/openapi.json

samwaterbury · 2025-09-22T18:15:24Z

src/client/activities/track.ts

+import { getCurrentPageProperties } from '../utils/helpers';
+import Activity from './activity';
+
+export const UNIFY_INTENT_TRACK_URL = `${UNIFY_INTENT_V1_URL}/track`;


Important: can you change this constant:

intent-js-client/src/client/constants.ts

Line 1 in 54b87dd

export const UNIFY_INTENT_V1_URL = 'https://unifyintent.com/analytics/api/v1';

To the updated value:

export const UNIFY_INTENT_V1_URL = 'https://api.unifyintent.com/analytics/v1';

The old URL will continue to work but I want to start to migrate us over to this URL for consistency with our other new public APIs.

…dentify traits, remove anonymous visitor ID

MattHsiung · 2025-09-23T18:04:44Z

src/client/activities/activity.ts

  private getBaseActivityPayload = (): AnalyticsEventBase => ({
    type: this.getActivityType(),
-    anonymousUserId: this._intentContext.identityManager.getOrCreateVisitorId(),
+    visitorId: this._intentContext.identityManager.getOrCreateVisitorId(),


would this be breaking at all?

@MattHsiung the API already supports the new param and the old one is optional

MattHsiung · 2025-09-23T18:14:45Z

src/client/utils/helpers.ts

+export function getDomainForEmail(email: string): string | null {
+  return email.split('@')[1];
+}


Suggested change

export function getDomainForEmail(email: string): string | null {

return email.split('@')[1];

}

export function getDomainForEmail(email: string) {

return email.split('@').at(1);

}

add ?? null if you needed it to return null specifically

solastley added 6 commits September 19, 2025 21:10

add track method to intent client with WIP types

446200d

finish track method implementation, add auto-tracking

428d83b

replace auto-tracking of all buttons with customizable CSS selector t…

c1808d6

…racking

update docs

4226f88

add table of contents to README

841a972

add some anchor links to docs

110cab3

solastley requested review from jonathandai, MattHsiung, samwaterbury, NoahCzelusta, aaug1-unify and a team September 22, 2025 00:36

bump version to 1.5.0

2479f73

aaug1-unify approved these changes Sep 22, 2025

View reviewed changes

solastley added 3 commits September 22, 2025 09:07

add optional Company and Person to identify, export more types

541dc79

improve navattic and default data parsing

9969ff6

remove unused constants

d8e5ccd

samwaterbury approved these changes Sep 22, 2025

View reviewed changes

solastley added 5 commits September 22, 2025 14:38

update docs, update API URL, switch to X-Write-Key for auth, remove i…

d610af8

…dentify traits, remove anonymous visitor ID

fix tests

f6659cf

fix default attribute

a06a8d3

add error handling

ca73d8b

remove some unused code

01ceccd

MattHsiung approved these changes Sep 23, 2025

View reviewed changes

solastley added 3 commits September 23, 2025 14:45

fix getDomainForEmail nullable logic

4b33374

update logger endpoint

5579db4

add disabled class check to isActionableElement

f6d640f

solastley mentioned this pull request Sep 25, 2025

feat: expose .track() method for custom event tracking #23

Closed

check if userAgentData is defined before accessing

8d0d182

solastley merged commit d057a01 into main Sep 26, 2025

solastley deleted the sa--track branch September 26, 2025 15:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add `track` and click auto-tracking to intent client #26

Add `track` and click auto-tracking to intent client #26

Uh oh!

solastley commented Sep 22, 2025

Uh oh!

aaug1-unify Sep 22, 2025 •

edited

Loading

Uh oh!

solastley Sep 22, 2025

Uh oh!

aaug1-unify Sep 22, 2025

Uh oh!

samwaterbury left a comment

Uh oh!

samwaterbury Sep 22, 2025

Uh oh!

samwaterbury Sep 22, 2025

Uh oh!

samwaterbury Sep 22, 2025

Uh oh!

samwaterbury Sep 22, 2025

Uh oh!

MattHsiung Sep 23, 2025

Uh oh!

solastley Sep 23, 2025

Uh oh!

MattHsiung Sep 23, 2025

Uh oh!

MattHsiung Sep 23, 2025

Uh oh!

Uh oh!

	NOTE:: See [@unifygtm/intent-react](https://www.npmjs.com/package/@unifygtm/intent-react) if you are using React.
	NOTE: See [@unifygtm/intent-react](https://www.npmjs.com/package/@unifygtm/intent-react) if you are using React.

Add track and click auto-tracking to intent client #26

Add track and click auto-tracking to intent client #26

Uh oh!

Conversation

solastley commented Sep 22, 2025

Uh oh!

aaug1-unify Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samwaterbury left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Add `track` and click auto-tracking to intent client #26

Add `track` and click auto-tracking to intent client #26

aaug1-unify Sep 22, 2025 •

edited

Loading