Search documentation...

K
ChangelogBook a demoSign up

First party tracking

Proxying

You can run Hightouch Events on a custom domain by setting up a proxy. When using a proxy, clients send their event data to your domain rather than directly to Hightouch. This lets you have more control over your data.

Prerequisites

You'll need a certificate for whatever domain you plan to use for the proxy.

This guide uses Amazon Cloudfront, but any CDN or reverse proxy will work.

Proxying the JavaScript SDK

Out of the box, the JavaScript SDK is served from cdn.hightouch-events.com. But you can serve the JavaScript SDK from your own domain instead.

First, create a Cloudfront distribution with the following settings:

SettingValue
Origin domaincdn.hightouch-events.com
Origin pathLeave this blank
NameGive your distribution a unique name
Enable Origin ShieldNo
Compress objects automaticallyYes
Viewer protocol policyHTTPS only
Allowed HTTP methodsGET, HEAD
Restrict viewer accessNo
Cache key and origin requestsCache policy and origin request policy
Cache policyCachingOptimized
Origin request policyAllViewerExceptHostHeader
Response headers policyNone
Function associationsNo associations
Alternate domain name (CNAME)The domain you want to expose to clients
Custom SSL certificateSelect a certificate that corresponds to the CNAME you entered
Supported HTTP versionsEnable HTTP/2 and HTTP/3
Default root objectLeave this blank
Standard loggingOff
IPv6On

Then, point your clients to the CNAME you configured. If using the JavaScript snippet, you can do this by replacing cdn.hightouch-events.com in the body of the snippet with your CNAME.

Proxying events

By default, events are sent to hightouch-events.com. But you can configure Hightouch to send events to your own domain instead.

First, create a Cloudfront distribution with the following settings:

SettingValue
Origin domainus-east-1.hightouch-events.com
Origin pathLeave this blank
NameGive your distribution a unique name
Enable Origin ShieldNo
Compress objects automaticallyYes
Viewer protocol policyHTTPS only
Allowed HTTP methodsGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict viewer accessNo
Cache key and origin requestsCache policy and origin request policy
Cache policyCachingDisabled
Origin request policyAllViewer
Response headers policyNone
Function associationsNo associations
Alternate domain name (CNAME)The domain you want to expose to clients
Custom SSL certificateSelect a certificate that corresponds to the CNAME you entered
Supported HTTP versionsEnable HTTP/2 and HTTP/3
Default root objectLeave this blank
Standard loggingOff
IPv6On

Then, set your SDK's apiHost setting to the CNAME you configured. For example, if you are using the Browser SDK:

HtEventsBrowser.load(
  { writeKey: "WRITE_KEY" },
  { apiHost: "events.example.com" }
);

 


 

Intelligent Tracking Prevention

Intelligent Tracking Prevention (ITP) is an automatic feature of the Safari web browser, designed to limit user tracking. More specifically, the program is designed to prevent analytics libraries from using client-side Javascript to correlate user sessions. ITP configures the Safari browser in the following ways:

  1. Third-party cookies are blocked by default.
  2. First-party cookies (and localStorage) have a default expiry of 7 days.
  3. A user revisiting a website will restart the 7 day expiry.

Unfortunately, most analytics libraries persist session information by:

  1. Storing an identifier in a Cookie.
  2. Storing an identifier in localStorage.

A legacy analytics installation, one not working to mitigate ITP, will collect less accurate session data for Safari users. For example, a single user visiting a website on both 01/01/2023 and 01/15/2023 will look like two different users. After Safari deletes the first cookie on 01/08/2023, the web SDK will be forced to make a new cookie and a new identifier for the session occurring on 01/15/2023. Downstream, your warehouse will likely see these sessions as two different users. This simple inaccuracy may impact otherwise useful metrics generated from analytics tracking.

Mitigating ITP

When properly configured, Hightouch Events can store session identifiers outside of ITP's 7 day expiry. It does this by using first party, HTTPOnly cookies. These are not subject to Safari's 7 day expiry. These types of cookies are generally used for logging into a website and are less likely to be limited, even when dealing with anonymous users.

These "server cookies" must follow several rules put in place by ITP:

  1. The server providing the HTTPOnly cookie must be on the same domain as the website.
  2. If the server is on a subdomain of the website, its IP address must match the IP address that served the main HTML document.

In practice, this means that ITP mitigation requires customers to host some sort of web service responsible for returning HTTPOnly cookies to the browser. The service does not need to be complex; Hightouch has numerous example servers. The most important part of this HTTPCookieService is that it must be a first party service: routing a subdomain via DNS will not suffice.

In order for the HTTPCookieService to serve first party, HTTPOnly cookies, you'll need one of the following:

A webserver that handles both your HTML documents and your API. This would mean building the HTTPCookieService functionality into your regular webserver. As an example, you might already have a Java Spring server for handling regular website requests.

A reverse proxy that can forward path-dependent requests to different servers. This requires proxying your domain to both an HTTPCookieService and your regular webserver. As an example, you might already have something like NGINX that proxies HTML requests to one place and API requests to another.

A CDN that can run programmatic logic when matching certain path-dependent requests. If you already have a CDN, you may be able to add custom handlers without standing up new servers. This can be achieved with a variety of technologies like Amazon's Cloudfront, Lambda@Edge, or API Gateway. Cloudflare Workers can also work.

Client SDK setup

Once your HTTPCookieService is reachable on your domain, you may configure your Hightouch Events SDK to make use of it when generating Cookies:

import { HtEventsBrowser } from '@ht-sdks/events-sdk-js-browser'

const htevents = HtEventsBrowser.load(
  { writeKey: '<YOUR_WRITE_KEY>'},
  {
    apiHost: "us-east-1.hightouch-events.com", // HtEvents API remains the same
    httpCookieServiceOptions: {
      clearUrl: '/ht/clear', // route hosted on *your* domain and infra
      renewUrl: '/ht/renew', // route hosted on *your* domain and infra
    }
  },
)

htevents.identify('hello world')

document.body?.addEventListener('click', () => {
  htevents.track('documentBodyClick')
})

Server setup

The Events SDK expects to interact with a customer's HTTPCookieService that implements a specific spec for two routes. You can name the endpoints whatever you want, as long as you configure the client SDK to call those endpoints.

An API for creating server and browser cookies

This route should look for the following browser cookies (from Events SDK):

  • request.headers.get("Cookie")["htjs_anonymous_id"]
  • request.headers.get("Cookie")["htjs_user_id"]

This route should return these values as server cookies:

  • response.cookie("htjs_anonymous_id_srvr", anonVal, {httpOnly:true, ...})
  • response.cookie("htjs_user_id_srvr", userIdVal, {httpOnly:true, ...})

If there are no browser cookies found, return any server cookies as browser cookies:

  • anonVal = request.headers.get("Cookie")["htjs_anonymous_id_srvr"]
  • userIdVal = request.headers.get("Cookie")["htjs_user_id_srvr"]
  • response.cookie("htjs_anonymous_id", anonVal, ...)
  • response.cookie("htjs_user_id", userIdVal, ...)

An API for clearing server cookies

This route should look for server cookies and clean them:

  • res.cookie("htjs_anonymous_id_srvr", "", {maxAge: 0, httpOnly:true, ...});
  • res.cookie("htjs_user_id_srvr", "", {maxAge: 0, httpOnly:true, ...});

API spec

The spec of the actual request and response payloads are kept intentionally vague. The spec should fit a variety of server environments.

The Events SDK only requires that the server: A) handles cookies and B) returns a 200 status code.

Server examples

More information

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: Apr 16, 2024

On this page

ProxyingPrerequisitesProxying the JavaScript SDKProxying eventsIntelligent Tracking PreventionMitigating ITPClient SDK setupServer setupAn API for creating server and browser cookiesAn API for clearing server cookiesAPI specServer examplesMore information

Was this page helpful?