Plugin Framework - Heap Event Message Schema
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
- User Metadata Event Message
- Session Metadata Event Message
- Pageview Metadata Event Message
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 |
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 |
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 |
Updated 3 months ago