DRAFT Branch Event Ontology

Branch's Event Ontology Data Schema is a unified format that is shared across all Branch products.

Events Included

We split out events into logical groupings. We now have the following distinct event groupings:

  • impression
  • click
  • web-to-app auto-redirect
  • Branch CTA view
  • sms sent
  • open
  • install
  • reinstall
  • web session start
  • pageview
  • commerce event
  • custom event
  • content event
  • user lifecycle event


Install Event Changes Post iOS 14.5

Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in

For additional information on changes post iOS 14.5, visit our FAQ Pages

The last four are groupings of multiple events.

  • Custom events are any events you choose to track with Branch that fall outside our list of standard events.
  • Commerce events include a short list of events such as PURCHASE that involve e-commerce.
  • Content events include a short list of events such as VIEW_ITEM that involve content and are not directly related to e-commerce.
  • User lifecycle events are events marking a distinct action completed by a user as they progress through your app, such as COMPLETE_REGISTRATION.

Branch Standard Events

Event NameEvent CategoryiOSAndroidWeb and API
Add To CartCommerce EventBranchStandardEventAddToCartBRANCH_STANDARD_EVENT.ADD_TO_CARTADD_TO_CART
Add To WishlistCommerce EventBranchStandardEventAddToWishlistBRANCH_STANDARD_EVENT.ADD_TO_WISHLISTADD_TO_WISHLIST
View CartCommerce EventBranchStandardEventViewCartBRANCH_STANDARD_EVENT.VIEW_CARTVIEW_CART
Initiate PurchaseCommerce EventBranchStandardEventInitiatePurchaseBRANCH_STANDARD_EVENT.INITIATE_PURCHASEINITIATE_PURCHASE
Add Payment InfoCommerce EventBranchStandardEventAddPaymentInfoBRANCH_STANDARD_EVENT.ADD_PAYMENT_INFOADD_PAYMENT_INFO
Click AdCommerce EventBranchStandardEventClickAdBRANCH_STANDARD_EVENT.CLICK_ADCLICK_AD
PurchaseCommerce EventBranchStandardEventPurchaseBRANCH_STANDARD_EVENT.PURCHASEPURCHASE
ReserveCommerce EventBranchStandardEventReserveBRANCH_STANDARD_EVENT.RESERVERESERVE
Spend CreditsCommerce EventBranchStandardEventSpendCreditsBRANCH_STANDARD_EVENT.SPEND_CREDITSSPEND_CREDITS
View AdCommerce EventBranchStandardEventViewAdBRANCH_STANDARD_EVENT.VIEW_ADVIEW_AD
View CartCommerce EventBranchStandardEventViewCartBRANCH_STANDARD_EVENT.VIEW_CARTVIEW_CART
SearchContent EventBranchStandardEventSearchBRANCH_STANDARD_EVENT.SEARCHSEARCH
View ItemContent EventBranchStandardEventViewItemBRANCH_STANDARD_EVENT.VIEW_ITEMVIEW_ITEM
View ItemsContent EventBranchStandardEventViewItemsBRANCH_STANDARD_EVENT.VIEW_ITEMSVIEW_ITEMS
RateContent EventBranchStandardEventRateBRANCH_STANDARD_EVENT.RATERATE
ShareContent EventBranchStandardEventShareBRANCH_STANDARD_EVENT.SHARESHARE
Initiate StreamContent EventBranchStandardEventInitiateStreamBRANCH_STANDARD_EVENT.INITIATE_STREAMINITIATE_STREAM
Complete StreamContent EventBranchStandardEventCompleteStreamBRANCH_STANDARD_EVENT.COMPLETE_STREAMCOMPLETE_STREAM
Complete RegistrationLifecycle EventBranchStandardEventCompleteRegistrationBRANCH_STANDARD_EVENT.COMPLETE_REGISTRATIONCOMPLETE_REGISTRATION
Complete TutorialLifecycle EventBranchStandardEventCompleteTutorialBRANCH_STANDARD_EVENT.COMPLETE_TUTORIALCOMPLETE_TUTORIAL
Achieve LevelLifecycle EventBranchStandardEventAchieveLevelBRANCH_STANDARD_EVENT.ACHIEVE_LEVELACHIEVE_LEVEL
Unlock AchievementLifecycle EventBranchStandardEventUnlockAchievementBRANCH_STANDARD_EVENT.UNLOCK_ACHIEVEMENTUNLOCK_ACHIEVEMENT
InviteLifecycle EventBranchStandardEventInviteBRANCH_STANDARD_EVENT.INVITEINVITE
LoginLifecycle EventBranchStandardEventLoginBRANCH_STANDARD_EVENT.LOGINLOGIN
Start TrialLifecycle EventBranchStandardEventStartTrialBRANCH_STANDARD_EVENT.START_TRIALSTART_TRIAL
SubscribeLifecycle EventBranchStandardEventSubscribeBRANCH_STANDARD_EVENT.SUBSCRIBESUBSCRIBE

Fields included

On each event, we provide a considerable amount of information. The following table has an overview. Several of the fields below are objects which themselves have many fields.

idstringa unique id for the event
namestringthe name of the event, such as CLICK, INSTALL, PURCHASE, or custom event names like "signup".
timestamplongunix timestamp in milliseconds for the event
user_data_opted_inbooleanWill always be false on first install. Will only be true on first app session after users opts in to Apple's App Tracking Transparency framework from paid ads
days_from_install_to_opt_inintnumber of days between when the first install (user_data_opted_in= false) and when this event occurred
days_from_last_attributed_touch_to_eventintnumber of days between when the last touch occurred and when this event subsequently occurred.
last_attributed_touch_typeenum { CLICK, WEB_TO_APP_AUTO_REDIRECT, IMPRESSION }whether the last attributed touch was an impression, a click, or a web to app auto redirect.
last_attributed_touch_timestamplongunix timestamp in milliseconds for the last attributed touch.
last_attributed_touch_dataobjectIf an impression, click, web to app auto redirect, branch cta view, or sms sent, this field contains the link data directly associated with the event. For all other events, this is the data associated with the last qualifying touch (click, impression, etc) to occur before this event. Subject to attribution windows, within which the last click or web to app auto redirect trumps a more recent impression.
days_from_last_cta_view_to_eventintnumber of days between when the last Branch CTA view occurred and when this event subsequently occurred (see datasource definition of cta view).
last_cta_view_timestamplongunix timestamp in milliseconds for the last Branch CTA view.
last_cta_view_dataobjectThis is the data associated with the last qualifying Branch CTA View to occur before this event. Subject to attribution windows, within which the last click or web to app auto redirect trumps a more recent impression.
first_event_for_userbooleanif this is the first time for this persona that this event has been triggered.
deep_linkedbooleantrue if the current app or web session resulted in the user being deep linked.
user_dataobjectdata associated with the user who triggered the event.
event_dataobjectdata associated with commerce or content events, but not specific to any one item.
content_itemsarray of objectArray of content items. A content item is any distinct item, whether a product, piece of content, restaurant, service, flight, hotel, or any kind of media (text, visual, audio.)
custom_dataobjectpartner-specified custom key-value pairs associated with an event, excluding Touches, Branch CTA view and SMS sent.

Full list of fields

If you are building an integration with Branch or simply wish to learn more about the fields we offer, please download the CSV file below. It provides a comprehensive list of events and fields, definitions and data types, along with which fields are available for which event types.

Full Event Ontology for Webhooks, Data Integrations and Exports

Additionally the Daily Export API CSVs will contain the following fields:

timestamp_isostring<s/span>timestamp as YYYY-MM-DD HH:MM:SS+0000
last_attributed_touch_timestamp_isostringlast_attributed_touch_timestamp as YYYY-MM-DD HH:MM:SS+0000
last_cta_view_timestamp_isostringlast_cta_view_timestamp as YYYY-MM-DD HH:MM:SS+0000
hash_versionstringwhether certain sensitive fields are hashed or unhashed

Updated 10 months ago

DRAFT Branch Event Ontology

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.