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 FIELD | Javascript | iOS | Android | Description |
|---|---|---|---|---|
| app.name | ✅ | ✅ | Name of the application. | |
| app.version | ✅ | ✅ | Version of the application. | |
| app.build | ✅ | ✅ | Build of the application. | |
| campaign.name | ✅ | Name of the campaign. | ||
| campaign.source | ✅ | Source of the campaign. | ||
| campaign.medium | ✅ | Medium of the campaign. | ||
| campaign.term | ✅ | Term of the campaign. | ||
| campaign.content | ✅ | Content of the campaign. | ||
| device.type | ✅ | ✅ | Type of the device. | |
| device.id | ✅ | ✅ | ID of the device. | |
| device.advertisingId | ✅ | ✅ | Advertising ID of the device. | |
| device.adTrackingEnabled | ✅ | ✅ | If ad tracking is enabled on the device. | |
| device.manufacturer | ✅ | ✅ | Manufacturer of the device. | |
| device.model | ✅ | ✅ | Model of the device. | |
| device.name | ✅ | ✅ | Name of the device. | |
| library.name | ✅ | ✅ | ✅ | Name of the library. |
| library.version | ✅ | ✅ | ✅ | Version of the library. |
| ip | ✅ | ✅ | ✅ | Current user’s IP address. |
| locale | ✅ | ✅ | ✅ | Locale string of the user. |
| network.bluetooth | ✅ | Bluetooth information. | ||
| network.carrier | ✅ | ✅ | Carrier information about the network connection. | |
| network.cellular | ✅ | ✅ | Cellular information about the network connection. | |
| network.wifi | ✅ | ✅ | WiFi information about the network connection. | |
| os.name | ✅ | ✅ | Name of the operating system. | |
| os.version | ✅ | ✅ | Version of the operating system. | |
| page.path | ✅ | Path of the current page in the browser. | ||
| page.referrer | ✅ | Referrer of the current page in the browser. | ||
| page.search | ✅ | Search of the current page in the browser. | ||
| page.title | ✅ | Title of the current page in the browser. | ||
| page.url | ✅ | URL of the current page in the browser. | ||
| screen.density | ✅ | Density of the device’s screen. | ||
| screen.height | ✅ | ✅ | Height of the device’s screen. | |
| screen.width | ✅ | ✅ | Width of the device’s screen. | |
| traits | ✅ | ✅ | Traits of the user. | |
| userAgent | ✅ | ✅ | User agent of the device making the request. | |
| userAgentData | ✅ | Information about the user’s timezone. | ||
| timezone | ✅ | ✅ | Information 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.