Search documentation...

K
ChangelogBook a demoSign up

Event tracking spec

Hightouch Events provides a flexible interface for tracking both user traits and user events. This flexibility allows you to adapt the tracking to your specific business context. With the tracking API, you can power a wide range of use cases, from user activation to detailed analytics.

Identify events

Identify events capture data about who your users are. This user context is vital for understanding and targeting your users. For example, you might use the collected identifiers in followup email campaigns, to segment your users by location, or to link anonymous and authenticated events.

Identify events have three main components:

  • An anonymous id. Anonymous ids are used to tie together events coming from the same device. Tying additional user ids or traits to the an anonymous id lets you better understand other events coming from the same device. The anonymous id is autogenerated and stored on the client, and is included in other event types such as Track events.
  • A user id. A user ID is a persistent identifier that's associated with the same user across devices and sessions. For example, it's common to use a user ID generated by your database. You should avoid using identifiers that may change, such as email, since if the user updates their email you will still want to treat them as the user.
  • Additional user traits. You may optionally provide additional user traits. Examples include the user's email, name, or age.

Example Payload for Identify Event:

{
  "type": "identify",
  "messageId": "111e984d-c93c-444c-b29c-f499a117c500",
  "traits": {
    "email": "kevin@hightouch.io"
  },
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "originalTimestamp": "2023-09-22T18:05:47.063Z",
  "sentAt": "2023-09-22T18:05:47.064Z"
}

Track events

Track events capture data on what the user is doing. Track events can capture a broad range of actions, such as clicking a button, completing a purchase, or creating a new account.

Additional information about the event can be included in the properties field. For example, for a Purchase Complete event, you may want to include the product ids of the purchased products.

When syncing into the warehouse, the event field is used to generate table names in the warehouse. Additionally, the properties field is autoconverted into columns in the warehouse.

Example Payload for Track Event:

{
  "type": "track",
  "messageId": "7b1e2872-4ebb-4779-b9ad-e7aa1a8eab82",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "event": "Purchase completed",
  "properties": {
    "cart_total": 24.99
  },
  "originalTimestamp": "2023-09-22T18:12:00.584Z",
  "sentAt": "2023-09-22T18:12:00.585Z"
}

Page events

Page events track the webpages users interact with. In most situations, you should automatically call the page load event when a page is loaded.

For single page apps, you should simulate page events in your routing layer.

Example Payload for Page Event:

{
  "type": "page",
  "messageId": "bb9fcbbd-9e19-4bfd-a726-7b1e7e44f8ba",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "properties": {
    "title": "Home"
  },
  "originalTimestamp": "2023-09-22T18:05:47.061Z",
  "sentAt": "2023-09-22T18:05:47.063Z"
}

Screen events

Screen events are the equivalent of page views for mobile apps. Like page events, you should automatically call the screen event when a mobile screen view is loaded.

Example Payload for Screen Event:

{
  "type": "screen",
  "messageId": "bb9fcbbd-9e19-4bfd-a726-7b1e7e44f8ba",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "properties": {
    "title": "Home"
  },
  "originalTimestamp": "2023-09-22T18:05:47.061Z",
  "sentAt": "2023-09-22T18:05:47.063Z"
}

Group events

Group events let you associate users with a larger group. For example, a user may be part of an organization, or family.

The traits field is optional, and can include information on traits on the group. For example, if linking a user to a company, you may include traits on the company such as the company size or location.

Example Payload for Group Event:

{
  "type": "group",
  "messageId": "d87596da-5f1e-40f4-a28a-7099290548b7",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "groupId": "456",
  "traits": { "company_name": "Hightouch" },
  "originalTimestamp": "2023-09-22T18:46:23.098Z",
  "sentAt": "2023-09-22T18:46:23.099Z"
}

Automatically captured fields

Below is a chart that shows you which context variables are populated automatically by the iOS, Android, and Javascript libraries.

CONTEXT FIELDJavascriptiOSAndroidDescription
app.nameName of the application.
app.versionVersion of the application.
app.buildBuild of the application.
campaign.nameName of the campaign.
campaign.sourceSource of the campaign.
campaign.mediumMedium of the campaign.
campaign.termTerm of the campaign.
campaign.contentContent of the campaign.
device.typeType of the device.
device.idID of the device.
device.advertisingIdAdvertising ID of the device.
device.adTrackingEnabledIf ad tracking is enabled on the device.
device.manufacturerManufacturer of the device.
device.modelModel of the device.
device.nameName of the device.
library.nameName of the library.
library.versionVersion of the library.
ipCurrent user’s IP address.
localeLocale string of the user.
network.bluetoothBluetooth information.
network.carrierCarrier information about the network connection.
network.cellularCellular information about the network connection.
network.wifiWiFi information about the network connection.
os.nameName of the operating system.
os.versionVersion of the operating system.
page.pathPath of the current page in the browser.
page.referrerReferrer of the current page in the browser.
page.searchSearch of the current page in the browser.
page.titleTitle of the current page in the browser.
page.urlURL of the current page in the browser.
screen.densityDensity of the device’s screen.
screen.heightHeight of the device’s screen.
screen.widthWidth of the device’s screen.
traitsTraits of the user.
userAgentUser agent of the device making the request.
userAgentDataInformation about the user’s timezone.
timezoneInformation about the user’s timezone.
  • IP Addresses are captured by Hightouch's servers when a message is received for client-side events and is not captured by Hightouch's libraries.
  • userAgentData is only collected if the Client Hints API is available on the browser.

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: Sep 21, 2023

On this page

Automatically captured fields

Was this page helpful?