🚧
Be cautious when modifying event messages
Within this document, we will be sharing a subset of the properties on our event messages. When implementing a transformer, there may be additional properties not detailed in this document.
Avoid modifying these properties as they may be vital for Heap analysis

Base Event Message Scheme

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for an event
`type` (do not modify)	`string`	`required` event type associated with the message metadata user event: `meta_user` metadata session event: `meta_session` metadata pageview event: `meta_pageview` track event: `core_track`
`info` (do not modify)	`object`	`required` raw event information used for event message data construction
`data`	`EventMessage`	`required` message constructed by transformers to be sent to Heap

All event messages will be structured as noted above. In particular, data is where any modifications to the event payload should occur. We have 4 types of EventMessage which will be detailed in the subsequent sections:

Track Event Message Schema

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the interaction event
`time` (do not modify)	`number`	`required` start timestamp of the pageview
`pageview_info`	PageviewInfo	`required` information associated with the current pageview
`session_info`	SessionInfo	`required` information associated with the current session
`event.interaction`	InteractionMessage	`optional` information about the interaction event, if applicable captured for `change`, `click`, and `submit` events
`event.custom`	CustomMessage	`optional` information about the manual track event, if applicable captured for `heap.track` events
`properties`	`object`	`optional` custom pageview properties. key must be a `string` value must be a `string`, `number`, `boolean`, or `number`

Example Interaction Track Event Message (click)

{
   "id":"4862784210443237",
   "type":"core_track",
   "data":{
      "id":"4862784210443237",
      "time":1695772367625,
      "env_id":"2448354216",
      "user_id":"6772334287318949",
      "base_library":{
         "name":"web",
         "version":"5.0",
         "platform":"web"
      },
      "device":{
         "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
         "uach":{
            "model":"",
            "platform_version":"12.3.0",
            "browser_version":"116.0.5845.187"
         }
      },
      "session_info":{
         "time":1695771981608,
         "referrer":"",
         "id":"4648187408605516",
         "search_keyword":"",
         "utm":{
            "source":"",
            "medium":"",
            "term":"",
            "content":"",
            "campaign":""
         },
         "initial_pageview_info":{
            "time":1695771981608,
            "id":"3495395863577351",
            "title":"",
            "url":{
               "domain":"jamesnghiem.github.io",
               "path":"/redirect-test/",
               "query":"?test=1234",
               "hash":""
            },
            "source_properties":{
               "screen_height":879,
               "screen_width":1262
            }
         }
      },
      "pageview_info":{
         "time":1695771981608,
         "id":"3495395863577351",
         "url":{
            "domain":"jamesnghiem.github.io",
            "path":"/redirect-test/",
            "query":"?test=1234",
            "hash":""
         },
         "title":"",
         "source_properties":{
            "screen_height":879,
            "screen_width":1262
         }
      },
      "event":{
         "interaction":{
            "kind":"BUILTIN_KIND_CLICK",
            "hierarchy":"@h2;|",
            "nodes":[
               {
                  "tagName":"h2",
                  "id":null,
                  "classes":[],
                  "attributes":[],
                  "heapRedactedAttributes":[],
                  "targetText":"for ted"
               }
            ]
         }
      },
      "source_library":{
         "name":"autotrack",
         "version":"0.0.0"
      }
   }
}

Example Custom Track Event Message

{
   "id":"6593488158485448",
   "type":"core_track",
   "info":{
      "event":"custom track event",
      "properties":{
         "isCustom":true,
         "date":"9/26/2023"
      },
      "isAutotrack":false
   },
   "data":{
      "id":"6593488158485448",
      "time":1695772229848,
      "env_id":"2448354216",
      "user_id":"6772334287318949",
      "base_library":{
         "name":"web",
         "version":"5.0",
         "platform":"web"
      },
      "device":{
         "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
         "uach":{
            "model":"",
            "platform_version":"12.3.0",
            "browser_version":"116.0.5845.187"
         }
      },
      "session_info":{
         "time":1695771981608,
         "referrer":"",
         "id":"4648187408605516",
         "search_keyword":"",
         "utm":{
            "source":"",
            "medium":"",
            "term":"",
            "content":"",
            "campaign":""
         },
         "initial_pageview_info":{
            "time":1695771981608,
            "id":"3495395863577351",
            "title":"",
            "url":{
               "domain":"jamesnghiem.github.io",
               "path":"/redirect-test/",
               "query":"?test=1234",
               "hash":""
            },
            "source_properties":{
               "screen_height":879,
               "screen_width":1262
            }
         }
      },
      "pageview_info":{
         "time":1695771981608,
         "id":"3495395863577351",
         "url":{
            "domain":"jamesnghiem.github.io",
            "path":"/redirect-test/",
            "query":"?test=1234",
            "hash":""
         },
         "title":"",
         "source_properties":{
            "screen_height":879,
            "screen_width":1262
         }
      },
      "event":{
         "custom":{
            "name":"custom track event",
            "properties":{
               "isCustom":true,
               "date":"9/26/2023"
            }
         }
      }
   }
}

Custom Message

Property	Type	Description
`name`	`string`	`required` name of the custom track event first argument of `heap.track`
`properties`	`object`	`optional` custom track event properties second argument of `heap.track`

Property

Type

Description

name

string

required
name of the custom track event

first argument of heap.track

properties

object

optional
custom track event properties

second argument of heap.track

Interaction Message

Property	Type	Description
`hierarchy`	`string`	`required` DOM hierarchy string associated with the interaction event
`nodes`	Array<ElementNode>	`required` Node representation of the hierarchy begins with the target element and traverses upwards

Property

Type

Description

hierarchy

string

required
DOM hierarchy string associated with the interaction event

nodes

Array<ElementNode>

required
Node representation of the hierarchy

begins with the target element and traverses upwards

Element Node

🚧
Only modifications to the targetText will be persisted. Modifications to any other property will not change the captured hierarchy string.

Property	Type	Description
`tagName`	`string`	`required` tag of the element node
`id`	`string`	`required` id of the element node
`classes`	`Array<string>`	`required` list of the element's class names
`attributes`	`Array<HTMLAttribute>`	`required` list of the element's attributes
`href`	`string`	`optional` href of the element node
`targetText`	`string`	`optional` text of the element node this is only captured for the target element (first ElementNode of the array)

Metadata Event Message Schema

User Message

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the user
`time` (do not modify)	`number`	`required` start timestamp of the user
`user`	UserInfo	`required` information associated with the current user

Example User Metadata Event Message

{
   "type":"meta_user",
   "id":"6772334287318949",
   "data":{
      "time":1695771981608,
      "id":"6772334287318949",
      "user_id":"6772334287318949",
      "base_library":{
         "name":"web",
         "version":"5.0",
         "platform":"web"
      },
      "device":{
         "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
         "uach":{
            "model":"",
            "platform_version":"12.3.0",
            "browser_version":"116.0.5845.187"
         }
      },
      "env_id":"2448354216",
      "user":{
         "time":1695771981608,
         "id":"6772334287318949",
         "initial_session_info":{
            "referrer":"",
            "time":1695771981608,
            "id":"4648187408605516",
            "search_keyword":"",
            "utm":{
               "source":"",
               "medium":"",
               "term":"",
               "content":"",
               "campaign":""
            },
            "initial_pageview_info":{
               "time":1695771981608,
               "id":"3495395863577351",
               "url":{
                  "domain":"jamesnghiem.github.io",
                  "path":"/redirect-test/",
                  "query":"?test=1234",
                  "hash":""
               },
               "source_properties":{
                  "screen_height":879,
                  "screen_width":1262
               }
            }
         }
      }
   }
}

Session Message

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the session
`time` (do not modify)	`number`	`required` start timestamp of the user
`session_info`	SessionInfo	`required` information associated with the current session

Example Session Metadata Event Message

{
   "type":"meta_session",
   "id":"4648187408605516",
   "data":{
      "time":1695771981608,
      "id":"4648187408605516",
      "env_id":"2448354216",
      "user_id":"6772334287318949",
      "base_library":{
         "name":"web",
         "version":"5.0",
         "platform":"web"
      },
      "device":{
         "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
         "uach":{
            "model":"",
            "platform_version":"12.3.0",
            "browser_version":"116.0.5845.187"
         }
      },
      "session_info":{
         "time":1695771981608,
         "referrer":"",
         "id":"4648187408605516",
         "search_keyword":"",
         "utm":{
            "source":"",
            "medium":"",
            "term":"",
            "content":"",
            "campaign":""
         },
         "initial_pageview_info":{
            "time":1695771981608,
            "id":"3495395863577351",
            "title":"",
            "url":{
               "domain":"jamesnghiem.github.io",
               "path":"/redirect-test/",
               "query":"?test=1234",
               "hash":""
            },
            "source_properties":{
               "screen_height":879,
               "screen_width":1262
            }
         }
      },
      "session":{}
   }
}

Pageview Message

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the pageview
`time` (do not modify)	`number`	`required` start timestamp of the user
`pageview_info`	PageviewInfo	`required` information associated with the current pageview

Example Pageview Metadata Event Message

{
   "type":"meta_pageview",
   "id":"6899501780283694",
   "data":{
      "time":1695771155484,
      "id":"6899501780283694",
      "env_id":"2448354216",
      "user_id":"3251430901129913",
      "base_library":{
         "name":"web",
         "version":"5.0",
         "platform":"web"
      },
      "device":{
         "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36",
         "uach":{
            "model":"",
            "platform_version":"12.3.0",
            "browser_version":"116.0.5845.187"
         }
      },
      "session_info":{
         "time":1695770971484,
         "referrer":"",
         "id":"5490251667124630",
         "search_keyword":"",
         "utm":{
            "source":"",
            "medium":"",
            "term":"",
            "content":"",
            "campaign":""
         },
         "initial_pageview_info":{
            "time":1695770971484,
            "id":"8057529591957585",
            "title":"",
            "url":{
               "domain":"jamesnghiem.github.io",
               "path":"/strict-csp/",
               "query":"",
               "hash":""
            },
            "source_properties":{
               "screen_height":879,
               "screen_width":1728
            }
         }
      },
      "pageview_info":{
         "time":1695771155484,
         "id":"6899501780283694",
         "url":{
            "domain":"jamesnghiem.github.io",
            "path":"/redirect-test/",
            "query":"",
            "hash":""
         },
         "title":"",
         "source_properties":{
            "screen_height":879,
            "screen_width":849
         }
      },
      "pageview":{}
   }
}

Shared Property Schema

User Information

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the user
`time` (do not modify)	`number`	`required` start timestamp of the user
`identity`(do not modify)	`string`	`optional` identity of the user
`initial_session_info`	SessionInfo	`optional` information associated with the first session of the user

Session Information

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the session
`time` (do not modify)	`number`	`required` start timestamp of the session
`referrer`	`string`	`optional` page linking to the site that initiated the session
`search_keyword`	`string`	`optional` search keyword of the referrer
`utm.source`	`string`	`optional` UTM source parameter of the first page of the session
`utm.medium`	`string`	`optional` UTM medium parameter of the first page of the session
`utm.term`	`string`	`optional` UTM term parameter of the first page of the session
`utm.content`	`string`	`optional` UTM content parameter of the first page of the session
`utm.campaign`	`Object`	`optional` UTM campaign parameter of the first page of the session
`initial_pageview_info`	PageviewInfo	`optional` information associated with the first pageview of the session

Pageview Information

Property	Type	Description
`id` (do not modify)	`string`	`required` unique numerical string identifier for the pageview
`time` (do not modify)	`number`	`required` start timestamp of the pageview
`title`	`string`	`optional` title of the page
`url.domain`	`string`	`optional` domain of the pageview URL
`url.path`	`string`	`optional` path of the pageview URL
`url.query`	`string`	`optional` query parameters of the pageview URL
`url.hash`	`string`	`optional` hash fragment of the pageview URL
`previous_page`	`string`	`optional` previous page path visited in this session
`properties`	`Object`	`optional` custom pageview properties key must be a `string` value must be a `string`, `number`, `boolean`, or `number`