API Reference

Common Event Object & Metadata

Insight Events are events that fire corresponding with customer behavior in your mobile app. These events help you better understand your customer's journey and enrich marketing attribution models.

Below you can review the list of events tracked and their associated metadata.

Event Object & Metadata

All event objects are posted with a standard set of identifiers and metadata which provide a high level overview on the context of the event and associate the event to a given app, user, and device identifier. The metadata available on every event includes: 

{
   "event_type":"AppOpened",
   "metadata":{
      "schema_id":"Event_AppOpened_5_0_0"
   },
   "event_id":"UNIQUE EVENT ID",
   "session_id":"UNIQUE SESSION ID",
   "device_id":"UNIQUE DEVICE ID",
   "app_id":"UNIQUE MERCHANT ID",
   "timestamp":1663008666001,
   "timestamp_iso":"2023-08-15T11:51:06.000-07:00"

}

event_typeString : The title of the event

schema_id String: The associated schema identifier for the event being sent

event_id String : The unique identifier of the event

session_id String : The unique identifier of the session associated with the event. There can be multiple events per single session

device_id String : The unique device identifier of the user's device

app_id String : The unique identifier of the merchant's app

timestamp Timestamp : The timestamp of the event

timestamp_iso String : The timestamp of the event in international standard format

Properties

Every event has a set of various properties that help us make sense of the context of the behavior and characteristics of a particular user. On every event payload that you receive from the Insights Data Streaming Webhook, the Event object will include the following properties:

  1. SessionProperties
  2. DeviceProperties
  3. AppProperties
  4. ShopifyProperties
  5. EventProperties

SessionProperties

Session Properties relate directly to the app user's session. This data will include more context on the source of a session, when a session started, and more! 

 "session_properties":{
      "session_id":"UNIQUE SESSION ID",
      "source":"direct",
      "session_type":"Returning",
      "session_start_time":1692140759000,
      "notification_id":null,
      "notification_type":null,
      "utm_source":null,
      "utm_medium":null,
      "utm_campaign":null,
      "utm_content":null,
      "utm_term":null,
      "notification_auth_type":null,
      "external_notification_id":null,
      "segment_id":null,
   }

session_id String: The unique identifier of every user session in the app

source String: A value or parameter tracking where the session originated from. This value is stamped on all events of a session. The default is "direct"

session_type String: The type of session that indicates if this is a returning or first time user. This will be "new" or "returning"

session_start_time Integer: The recorded start time of a session

notification_id String: The unique identifier of the notification that lead to the session (if applicable). If a source of the session is "notification" then this field will be

notification_type String: The type of push notification associated with the message

utm_source String : The attached utm source if the session source occurs from a deeplink

utm_medium String : The identifying medium or type of link that was used

utm_campaign String : The specific associated campaign in the deeplink

utm_content String : The content the user clicked in order to enter the session

utm_term String : Identifies any search terms used in the deeplink

notification_auth_type String : Certain notifications are able to be sent via provisional authentication or standard authentication. This field indicates the authorization of the notification that was sent

external_notification_id String : The unique identifier of a notification sent from a third party source or integration

segment_id String : The unique identifier of an automated push campaign. These campaigns would distinguish between welcome campaigns, abandoned cart messages, and any other automations enabled

DeviceProperties

DeviceProperties, unlike SessionProperties, are all of the properties related to the user's device. This data gives you context into any of the devices that download and use your app. An example of the device properties can be seen below: 

"device_properties":{
      "ip":"USER’S IP",
      "os":"iOS",
      "model":"arm64",
      "orientation":"portrait",
      "carrier":"",
      "radio":"Wifi",
      "manufacturer":"Apple",
      "lib_version":"4.1.5",
      "country":"US",
      "locale":"en",
      "wifi":true,
      "app_version":null,
      "tapcart_build":null,
      "external_build":null,
      "os_version":"15.5",
      "tapcart_commit_hash":null,
      "consumer_type":"Returning",
      "device_id":"UNIQUE DEVICE ID",
      "prev_push_enabled":false,
      "push_enabled":false
   }

ip String: The user's IP address

os String: The user's operating system

model String: The user's device model ID

orientation String: The device's screen orientation

carrier String: Wireless carrier of the device owner

radio String: Current cellular network communication standard

manufacturer String: The user's device manufacturer

lib_version String: Version of the Mixpanel library used to send this data

country String: The country of the event sender parsed from the IP property or the Latitude and Longitude properties

locale String: The country locale

wifi Boolean: Set to true if user's device has an active, available Wifi connection. The property will display false if not

app_version String: Tapcart app version number

tapcart_build String: Tapcart build name

external_build String: Global app build number

os_version String: Mobile operating system version of the device

tapcart_commit_hash String: Commit Hash of codebase used to build the app

consumer_type String: Signifies the business defined user state. This will be either new or returning

device_id String: The user's unique device id

prev_push_enabled Boolean: Will be based on the previous value of push_enabled that exists from the system. This will update on every SessionStarted

push_enabled Boolean: Will be based on whether or not the device has notifications currently enabled for the app. This will be updated on every SessionStarted event by checking whether or not the user has the notifications enabled on the system

AppProperties

AppProperties relate to certain settings applied in the merchant's app unique to the context of the user and their interactions.

   "app_properties":{
      "app_id":"UNIQUE MERCHANT ID",
      "currency_code":"USD",
      "app_version":"1.0.0",
      "tapcart_build":"10.4.0",
      "external_build":"10.4.0",
      "os_version":"15.5",
      "tapcart_commit_hash":null,
      "environment":"debug"
   }

app_id String: The unique merchant ID

currency_code String: The merchant’s default currency code

app_version String: Tapcart app version number

external_build String: Global app build number

os_version String: Mobile operating system version of the device

tapcart_commit_hash String: Commit Hash of Codebase used to build the app

environment String: The state of the mobile app and whether or not the event was coming from a debug version or a released version

ShopifyProperties:

ShopifyProperties are properties related to a logged in Shopify user. If a user creates an account and logs in, Tapcart is able to record information on that user. 

   "shopify_properties":{
      "shopify_user_id":"UNIQUE SHOPIFY USER ID",
      "logged_in":true 
   }

shopify_user_id String: User ID given by Shopify when they login or create an account

logged_in String: If the Shopify user is logged into the app