Installation
The Browser SDK can be installed by loading the Javascript via ascript tag, or directly bundled via a npm package.
To install using a script tag, add the following snippet to your site, replacing WRITE_KEY with the write key from your Event Source:
npm:
- Install the SDK by running
npm install @ht-sdks/events-sdk-js-browser - Import and initialize the SDK with the following:
API
Identify
Theidentify method is used to send an identify event.
If identify is called multiple times for the same user, the traits are
merged together.
Method signature:
Track
Thetrack method is used to send a track event.
Method signature:
Page
Thepage method is used to send a page event.
Method signature:
Group
Thegroup method sends a group event.
Method signature:
Reset
Thereset method resets the identify and group for the local session.
Specifically, it resets the anonymousId, userId, groupId, and traits.
The reset method should be called when users log out. This way, if the user
logs back in with another account, the userIds and traits from the different
sessions remain separate.
Method signature:
Single page applications
While Single Page Apps (SPAs) are great for many reasons, they do require some extra consideration in order to set up client-side tracking than with a traditional webpage. By default, the Hightouch htevents.js library doesn’t generate or store the referrer value. Instead, the referrer value you see in the payload is the value returned bydocument.referrer directly from the browser, and the URL value is the canonical URL on the page.
When a user navigates between pages on an SPA website, there won’t be a referrer because there is no concept of a new page since it’s all a single page load. This means that the referrer will always be the same as it was on the first page call where someone was first directed to your site. However, in order to circumvent this, you can manually set the referrer and URL in your Hightouch calls by updating the context object.
For example, a Page call with the referrer and URL manually set looks like this:
Tracking emulated page views
Your application should update the URL in the address bar to emulate traditional webpage navigation. Full page requests aren’t made in most of these instances since the resources are loaded on initial page load. This means that the Page call in the traditional htevents.js snippet won’t fire again as a user navigates around your site. You should still place the snippet in the head of your site, but you should remove the Page call and fire it whenever you’re emulating a page load. Hightouch recommends that you call Page from the same block of logic that updates the view and URL path like below:QueryString API
The Browser SDK can triggertrack and identify events based on the URL query string. You can use this when tracking email click-throughs, social media clicks, and digital advertising.
Query parameters:
Example
The following URL:Configuration
TheuseQueryString option allows you to control the behavior of the query parameters. For example, you can entirely disable query string processing by setting useQueryString to false:
Cross Domain Tracking
Using the QueryString API you can easily track users across different domains. For example, if you have the following sites:- Site 1:
www.landing-page.com - Site 2:
www.product-page.com
userId from Site 1 to Site 2 using the ajs_uid query parameter.
identify event on Site 2 with userId: 123.
If you want to track anonymous users across domains, you can access the anonymousId on Site 1 using:
anonymousId from Site 1 to Site 2 using the ajs_aid query parameter. Note that the ajs_aid parameter does not automatically trigger an identify event.
Autocollected fields
The browser SDK autocollects the following fields within thecontext of each event:
These fields describe the environment of an event. They do not mean that the SDK automatically detects purchases, clicks, or other business actions.
The standard installation snippet explicitly calls
page(), which sends an initial page event.
On page events, the SDK adds default page fields to both context.page and properties. Explicit page properties or context can override those defaults.
See the event specification for user identifiers and server-captured IP addresses.
User traits
User traits normally come from your application’sidentify calls and are sent in the event’s top-level traits object.
The Browser SDK can also import trait values from these sources:
- URL parameters: The QueryString API reads
ajs_trait_*values whenajs_uidis present and passes validation, then callsidentifywith those values. During initialization, it uses the URL query string or a hash-fragment fallback when the query string is empty. This behavior is enabled by default. SetuseQueryString: falseto disable it. - Legacy cookies: During initialization, the SDK copies an existing
ajs_usercookie’straitsinto its trait store when persistence permits reading the cookie. Importing the cookie does not itself send anidentifyevent.
htjs_user_traits and reuse them in later identify events.
These traits are supplied values read from application calls, URLs, or storage. The SDK does not infer profile attributes such as a person’s name or email address.
Session tracking
A session is a group of “uninterrupted” events that were performed by the same visitor. The session resets once the session’s timeout has expired, and automatically refreshes when a new event is sent. For example, if the visitor views a couple pages, and then returns to your site after a day, the next day’s events will be considered a new session. The browser SDK automatically tracks asessionId field to track what events occurred in the same session. If two events occurred in the same session, they
will have the same session ID.
The session timeout can be adjusted from the default of 30 minutes when the SDK is initialized:
Campaign Attribution (UTM)
Hightouch automatically captures UTM parameters that you pass in URLs. You can also manually pass UTMs into thecontext.campaign field.
The SDK parses utm_* parameters from the event’s page query string, regardless of the referring domain. It adds them to context.campaign unless you provide that object yourself.
Campaign values are read from the page for each event. They are not persisted across pages, so pass them explicitly if subsequent pages should retain them.
Any parameter with the lowercase utm_ prefix and a nonempty suffix can populate context.campaign.
Only utm_campaign is renamed to campaign.name. Other parameters lose the prefix, so utm_id becomes campaign.id.
Common UTM parameters:
If you’d like UTM parameters to persist in subsequent calls, you’ll need to manually set those fields in
context.campaign. For example:
Cookies and LocalStorage
Hightouch stores cookies to track information about website visitors across multiple visits.htjs_user_id: ID tracking known or identified users as defined here.htjs_anonymous_id: ID tracking anonymous website visitors as defined here.htjs_group_id: ID tracking the group a user is associated with as defined here.htjs_sesh: Information about the user’s current session as defined here.
htjs_user_traits: Traits defined about the user being trackedhtjs_group_properties: Properties defined about the group being tracked
ajs_anonymous_id) and RudderStack (rl_anonymous_id), from accessible cookies or localStorage. It also supports the legacy _sio cookie.
The SDK can read an existing _ga cookie for context.amp.id. It also stores advertising-referrer attribution in s:context.referrer unless disableClientPersistence is enabled.
Disabling persistence prevents that attribution cookie from being read or written, but URL parameters can still populate the event’s attribution fields.
For more information on measures to increase persistence of cookies, please refer to our guide on proxying and server-side cookies.
Overriding messageId
If you need control over themessageId format, you can override it using a before plugin. A before plugin runs before the event is sent and lets you mutate the event object directly:
Example:
-, and _ in your custom messageId values. Other special characters aren’t supported.
Prebuilt plugins
Use Hightouch’s prebuilt plugins to add integrations without writing a plugin yourself. Each plugin is optional and must be enabled in your SDK configuration.Enrich events with Facebook parameters
The Facebook Parameters plugin collects Meta’sfbc and fbp values and attaches them to the context of every event. When you forward those events to Meta’s Conversions API, these parameters improve how well Meta matches events to people.
context.fbc: The Facebook click ID, derived from thefbclidURL parameter and stored in the_fbccookie.context.fbp: The Facebook browser ID, stored in the_fbpcookie.
facebook-params to the plugins option when you load the SDK.
If you installed with a script tag, add the option to the load call in the snippet:
npm, add the same option:
ParamBuilder writes the
_fbc, _fbp, or _fbi first-party cookies when the
SDK loads. If your site requires consent before setting tracking cookies, turn
on this plugin only after the visitor consents.fbc and fbp values.
Braze
Use the Braze plugin to forward Hightouch calls to the Braze Web SDK in the browser. This lets Braze evaluate in-app message triggers while the visitor is active, alongside normal event collection in Hightouch. Use version1.7.0 or later of the Hightouch Browser SDK. Install the Braze Web SDK alongside it:
identify calls as user updates and track calls as custom events. By default, Order Completed and Completed Order become purchases, with one purchase per product. Page forwarding is off by default; pageTracking: "name" forwards page calls as custom events.
When the plugin initializes Braze, automaticallyShowInAppMessages defaults to true. Set it to false if your application provides custom in-app message presentation. Your application configures Content Cards and push notifications.
If Braze is already initialized, pass instance: braze instead of apiKey, baseUrl, and sdk to reuse it. With an existing instance, your application manages message presentation and sessions. The automaticallyShowInAppMessages option does not apply.
See the Braze example for an application setup. If you’re replacing an mParticle kit, follow Migrate the mParticle Braze kit to preserve your existing mappings.