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"
}

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

Was this page helpful?