Search documentation...

K
ChangelogBook a demoSign up

Browser (Javascript) SDK

The Browser SDK makes it easy to track events in webpages.

Installation

The Browser SDK can be installed by loading the Javascript via a script 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:

<script type="text/javascript">
!function(){var e=window.htevents=window.htevents||[];if(!e.initialize)if(e.invoked)window.console&&console.error&&console.error("Hightouch snippet included twice.");else{e.invoked=!0,e.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"],e.factory=function(t){return function(){var n=Array.prototype.slice.call(arguments);return n.unshift(t),e.push(n),e}};for(var t=0;t<e.methods.length;t++){var n=e.methods[t];e[n]=e.factory(n)}e.load=function(t,n){var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src="https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(o,r),e._loadOptions=n,e._writeKey=t},e.SNIPPET_VERSION="0.0.1",
e.load('WRITE_KEY',{apiHost:'us-east-1.hightouch-events.com'}),
e.page()}}();
</script>

To install using npm:

  1. Install the SDK by running npm install @ht-sdks/events-sdk-js-browser
  2. Import and initialize the SDK with the following:
import { HtEventsBrowser } from "@ht-sdks/events-sdk-js-browser";
export const htevents = HtEventsBrowser.load(
  { writeKey: "WRITE_KEY" },
  { apiHost: "us-east-1.hightouch-events.com" }
);

API

Identify

The identify 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:

htevents.identify(userId, [traits], [context], [callback])

Method parameters:

ParameterTypeDescription
userIdStringThe user's persistent ID.
traitsObjectAdditional traits about the user, such as email and name.
contextObjectOverrides to values in the event context. By default, context contains information autocollected by the SDK.
callbackFunctionA callback that's invoked after the event is sent.

Track

The track method is used to send a track event.

Method signature:

htevents.track(event, [properties], [context], [callback])

Method parameters:

ParameterTypeDescription
eventStringThe event name (for example "Checked Out").
propertiesObjectAdditional properties about the event, such as product_id.
contextObjectOverrides to values in the event context. By default, context contains information autocollected by the SDK.
callbackFunctionA callback that's invoked after the event is sent.

Page

The page method is used to send a page event.

Method signature:

htevents.page(category, name, [properties], [context], [callback])

Method parameters:

ParameterTypeDescription
categoryStringThe page's category. For example, "Docs".
nameStringThe page's name. For example, "Getting started".
propertiesObjectAdditional properties about the event, such as url. By default, the SDK autocollects properties such as page referrer.
contextObjectOverrides to values in the event context. By default, context contains information autocollected by the SDK.
callbackFunctionA callback that's invoked after the event is sent.

Group

The group method sends a group event.

Method signature:

htevents.group(groupId, [traits], [context], [callback])

Method parameters:

ParameterTypeDescription
groupIdStringThe id for the group.
traitsObjectAdditional traits about the group, such as company_name.
contextObjectOverrides to values in the event context. By default, context contains information autocollected by the SDK.
callbackFunctionA callback that's invoked after the event is sent.

Reset

The reset 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:

htevents.reset()

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 by document.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:

htevents.page({
  referrer: 'https://hightouch.com/',
  url: 'https://hightouch.com/pricing/?ref=nav'
})

A Track call with these fields manually updated looks like this:

htevents.track('Example Event', {}, {page: {
  referrer: 'https://hightouch.com/',
  url: 'https://hightouch.com/pricing/?ref=nav'
}})

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:

// The new view has been called to render
htevents.page("Home")

To track more than the page field, pass those fields in as additional properties. Hightouch recommends that you use variables to set information about page properties, rather than hard-coding. In most SPA frameworks, you can automate this by attaching the Page call to the routing service.

QueryString API

The Browser SDK can trigger track 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:

ParameterDescriptionTriggers
ajs_uidThe userId for the identify event.This triggers an identify event.
ajs_eventThe name for the track event.This triggers a track event.
ajs_aidThe anonymousId for the user.This sets the anonymousId, by itself does not trigger any event.
ajs_prop_<property>A property to set on the track event.This sets a property on the resulting track event, by itself does not trigger any event.
ajs_trait_<trait>A trait to set on the identity event.This sets a trait on the resulting identify event, by itself does not trigger any event.

Example

The following URL:

https://hightouch.com/?ajs_uid=123&ajs_event=Clicked%20Email&ajs_aid=abc123&ajs_prop_emailCampaign=First+Touch&ajs_trait_name=John

would result in these calls:

htevents.identify('123', { name: 'John' });
htevents.track('Clicked Email', { 'emailCampaign': 'First Touch' });
htevents.user().anonymousId('abc123');

Configuration

The useQueryString 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:

htevents.load('WRITE_KEY', {
  useQueryString: false
})

You can also keep query string processing on, but enforce validation rules. For example:

htevents.load('WRITE_KEY', {
  useQueryString: {
    // set a pattern for anonymous id
    aid: /([A-Z]{10})/,
    // set a pattern for user id
    uid: /([A-Z]{6})/
  }
})

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

To track a user who starts on Site 1 and navigates to Site 2, you just need to pass the userId from Site 1 to Site 2 using the ajs_uid query parameter.

https://www.product-page.com/?ajs_uid=123

This will automatically trigger an 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:

htevents.user().anonymousId()

You can then pass the 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 the context of each event:

FieldDescription
page.pathThe current page's sanitized path, i.e. with search parameters and the site domain removed.
page.referrerThe referrer to the current page. An empty string denotes a direct referrer.
page.searchThe search parameter of the current page, if any
page.titleThe current page's title
page.urlThe current page's full URL
sessionIdAn identifier for the visitor's current session.
userAgentThe raw user agent string
userAgentDataParsed information on the user agent. This includes whether the visitor's device is a mobile device, and the platform of the device.
localeThe browser's locale
libraryInformation about the SDK version used to send the event.
timezoneThe visitor's local timezone.

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. 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 a sessionId field to track what events occurred in the same session. If two events occured 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:

e.load('YOUR_WRITE_KEY', {
  apiHost: 'us-east-1.hightouch-events.com',
  user: {
    sessions: {
      autoTrack:true,
      // Set the timeout to 60 minutes.
      timeout: 60*60*1000,
    }
  }
})

Campaign Attribution (UTM)

Hightouch automatically captures UTM parameters that you pass in URLs. You can also manually pass UTMs into the context.campaign field.

UTM parameters are only used when linking to your site from outside of your domain. When a visitor arrives to your site using a link containing UTM parameters, Hightouch's Browser SDK will automatically parse the URL query string and store UTM parameters within the context.campaign object as outlined here. These parameters do not persist to subsequent calls unless you pass them explicitly.

UTM parameters:

ParameterMappingDescription
utm_campaigncampaign.nameThis is the name of your campaign. All marketing activities that support this campaign need to have the same utm_campaign so that downstream analysis to measure performance for this specific campaign can be done off this primary key.
utm_mediumcampaign.mediumHow the traffic is coming to your site. Is it through email, a display ad, or an online forum? This ensures downstream analysis can easily see which channel performs the best.

eg. email, paid-display, paid-social, organic-social
utm_sourcecampaign.sourceWhere the traffic is specifically coming from. You can be specific here. This ensures downstream analysis can measure which specific source brings the most conversions.

eg. twitter, facebook, adroll
utm_contentcampaign.contentFor multiple calls to action on a single page, utm_content indicates which one. For example, on a website, there may be three different display ads. While the link on each display ad will have the same utm_campaign, utm_medium, and utm_source, the utm_content will be different.

eg. banner, left-side, bottom-side
utm_termcampaign.termThis is the parameter suggested for paid search to identify keywords for your ad. If you’re using Google Adwords and have enabled “autotagging”, then you don’t need to worry about this. Otherwise, you can manually pass the keywords from your search terms through this parameter so that you can see which keywords convert the most. Note that this parameter is reserved explicitly for search.

eg. toast, butter, jam

If you’d like UTM parameters to persist in subsequent calls, you’ll need to manually set those fields in context.campaign. For example:

htevents.page("My Page", {}, {
  campaign: {
    name: "TPS Innovation Newsletter",
    source: "Newsletter",
    medium: "email",
    term: "tps reports",
    content: "image link"
  },
});

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Mar 28, 2024

On this page

InstallationAPIIdentifyTrackPageGroupResetSingle page applicationsTracking emulated page viewsQueryString APIExampleConfigurationCross Domain TrackingAutocollected fieldsSession trackingCampaign Attribution (UTM)

Was this page helpful?