Event tracking helps you understand how a user moves through your app and what actions they are taking along the way. It's also how you get insight into when a user installs or reinstalls your app.
Some events are tracked automatically by Branch, while others are not. For those that aren't, you'll use the Branch SDK to log the event.
Types of Branch Events
There are 2 main categories of events: Standard and Custom.
Standard Events
Standard Events have properties that are pre-defined by Branch. There are 3 categories of Standard Events: Commerce, Content, and Lifecycle.
Standard Events have the following HTTP API endpoint:
POST /v2/event/standard
Content-Type: application/json
HTTP
Custom Events
Custom Events are for actions you want to track that Branch doesn't have a suitable Standard Event for. You can define your own properties for these types of events.
Custom Events have the following HTTP API endpoint:
POST /v2/event/custom
Content-Type: application/json
HTTP
Automatically tracked events
By default, the Branch SDKs track some events automatically (out-of-the-box). See the table below for specifics:
Event
Tracked Automatically by Mobile SDKs
Tracked Automatically by Web SDK
Click
✔️
✔️
Open
✔️
✔️ (called web_session_start)
Install
✔️
✔️
Reinstall
✔️
✔️
Impression
✔️
✔️
Journeys Dismissal
N/A
✔️
On web, open events are called web_session_start. This event is triggered every time a webpage with the web SDK opens in a new tab or when a user clicks on a Branch link and is redirected to a page with the web SDK. A user doing things like clearing the browser cache or navigating away from the webpage and the going back to it will reinitiate the web session.
Branch Universal Objects
Branch SDKs use the concept of a Branch Universal Object (BUO) to represent the thing you want to share. A BranchUniversalObject instance encapsulates a unique piece of content, such as an article, video, or item for sale.
When tracking app events, you will sometimes want to create a BUO first and then associate it with a Branch Event by adding the BUO instance to the Branch Event's contentItems field.
Attribution
For proper attribution, you must send certain parameters to Branch alongside these events as part of the user data:
developer_identityOR
browser_fingerprint_idOR
os=iOS AND idfaOR
os=iOS AND idfvOR
os=Android AND android_idOR
os=Android AND aaid
Ad network event mapping
When the Branch Ads feature is enabled, tracking Branch Standard Events will postback to the attributed Ad Network. For example, if you track a Standard PURCHASE Event through Branch, it will automatically map to Facebook's Purchase event (if the user is attributed to Facebook). These events will also have analytics like counts and cohorts.
Track events
The sections below outline each type of Branch Standard Event, as well as Custom Events. Included are code samples in a range of languages, so you can see how to log that event using your version of the Branch SDK.
Usage Limitations
Branch may implement caps or overages based on the number of events you are tracking. We recommend that you only track events that are useful for your analytics and attribution needs. This will also avoid unnecessary network calls being made by your app, leading to better app performance.
Track Commerce Events
Commerce Events include purchases and transactions, as well as actions related to carts and wishlists.
If you have the Branch Ads feature enabled, Commerce Events will automatically map to certain Ad Partners.
Currency and Exchange Rates
If you track Commerce Events without a currency, we assume the currency is USD.
If you track Commerce Events with a currency other than USD, we will convert the revenue specified to USD (using a recent exchange rate).
This allows you to easily visualize revenue on the Dashboard across many countries and currencies, because all units are USD.
The exchange rate is pulled from openexchangerates.org regularly and is generally within an hour of the real-time exchange rate. If you view raw Branch Events via either Webhooks or Exports, you can see the exchange rate used.
Event Name
iOS
Android
Web/API
Add To Cart
BranchStandardEventAddToCart
BRANCH_STANDARD_EVENT.ADD_TO_CART
ADD_TO_CART
Add To Wishlist
BranchStandardEventAddToWishlist
BRANCH_STANDARD_EVENT.ADD_TO_WISHLIST
ADD_TO_WISHLIST
View Cart
BranchStandardEventViewCart
BRANCH_STANDARD_EVENT.VIEW_CART
VIEW_CART
Initiate Purchase
BranchStandardEventInitiatePurchase
BRANCH_STANDARD_EVENT.INITIATE_PURCHASE
INITIATE_PURCHASE
Add Payment Info
BranchStandardEventAddPaymentInfo
BRANCH_STANDARD_EVENT.ADD_PAYMENT_INFO
ADD_PAYMENT_INFO
Click Ad
BranchStandardEventClickAd
BRANCH_STANDARD_EVENT.CLICK_AD
CLICK_AD
Purchase
BranchStandardEventPurchase
BRANCH_STANDARD_EVENT.PURCHASE
PURCHASE
Reserve
BranchStandardEventReserve
BRANCH_STANDARD_EVENT.RESERVE
RESERVE
Spend Credits
BranchStandardEventSpendCredits
BRANCH_STANDARD_EVENT.SPEND_CREDITS
SPEND_CREDITS
View Ad
BranchStandardEventViewAd
BRANCH_STANDARD_EVENT.VIEW_AD
VIEW_AD
Subscription and in-app purchase events
The Branch iOS and Android SDKs offer certain methods that make tracking subscription and in-app purchase events simpler. These methods allow you to convert standard purchase events from Apple and Google into a Branch Event without needing to create and populate a Branch Universal Object first.
Examples
// Create a BranchUniversalObject with your content datalet branchUniversalObject =BranchUniversalObject.init()// Add data to the branchUniversalObject as needed
branchUniversalObject.canonicalIdentifier ="item/12345"
branchUniversalObject.canonicalUrl ="https://branch.io/item/12345"
branchUniversalObject.title ="My Item Title"
branchUniversalObject.contentMetadata.contentSchema =.commerceProduct
branchUniversalObject.contentMetadata.quantity =1
branchUniversalObject.contentMetadata.price =23.20
branchUniversalObject.contentMetadata.currency =.USD
branchUniversalObject.contentMetadata.sku ="1994320302"
branchUniversalObject.contentMetadata.productName ="my_product_name1"
branchUniversalObject.contentMetadata.productBrand ="my_prod_Brand1"
branchUniversalObject.contentMetadata.productCategory =.apparel
branchUniversalObject.contentMetadata.productVariant ="XL"
branchUniversalObject.contentMetadata.condition =.new
branchUniversalObject.contentMetadata.customMetadata =["custom_key1":"custom_value1","custom_key2":"custom_value2"]// Create an eventlet event =BranchEvent.standardEvent(.purchase)// Add the BranchUniversalObject with the content (do not add an empty branchUniversalObject)
event.contentItems =[ branchUniversalObject ]// Add relevant event data
event.alias ="my custom alias"
event.transactionID ="12344555"
event.currency =.USD
event.revenue =1.5
event.shipping =10.2
event.tax =12.3
event.coupon ="test_coupon"
event.affiliation ="test_affiliation"
event.eventDescription ="Event_description"
event.searchQuery ="item 123"
event.customData =["Custom_Event_Property_Key1":"Custom_Event_Property_val1","Custom_Event_Property_Key2":"Custom_Event_Property_val2"]// Log the event
event.logEvent()
Swift
// Create a BranchUniversalObject with your content data
BranchUniversalObject *branchUniversalObject =[BranchUniversalObject new];// Add data to the branchUniversalObject as needed
branchUniversalObject.canonicalIdentifier =@"item/12345";
branchUniversalObject.canonicalUrl =@"https://branch.io/item/12345";
branchUniversalObject.title =@"My Item Title";
branchUniversalObject.contentMetadata.contentSchema = BranchContentSchemaCommerceProduct;
branchUniversalObject.contentMetadata.quantity =1;
branchUniversalObject.contentMetadata.price =[[NSDecimalNumber alloc] initWithDouble:23.20];
branchUniversalObject.contentMetadata.currency = BNCCurrencyUSD;
branchUniversalObject.contentMetadata.sku =@"1994320302";
branchUniversalObject.contentMetadata.productName =@"my_product_name1";
branchUniversalObject.contentMetadata.productBrand =@"my_prod_Brand1";
branchUniversalObject.contentMetadata.productCategory = BNCProductCategoryApparel;
branchUniversalObject.contentMetadata.productVariant =@"XL";
branchUniversalObject.contentMetadata.condition =@"NEW";
branchUniversalObject.contentMetadata.customMetadata =(NSMutableDictionary*)@{@"content_custom_key1":@"content_custom_value1",@"content_custom_key2":@"content_custom_value2"};// Create an event
BranchEvent *event =[BranchEvent standardEvent:BranchStandardEventAddToCart];// Add the BranchUniversalObject with the content (do not add an empty branchUniversalObject)
event.contentItems =(id)@[ branchUniversalObject ];// Add relevant event data
event.alias =@"my custom alias";
event.transactionID =@"12344555";
event.currency = BNCCurrencyUSD;
event.revenue =[NSDecimalNumber decimalNumberWithString:@"1.5"];
event.shipping =[NSDecimalNumber decimalNumberWithString:@"10.2"];
event.tax =[NSDecimalNumber decimalNumberWithString:@"12.3"];
event.coupon =@"test_coupon";
event.affiliation =@"test_affiliation";
event.eventDescription =@"Event_description";
event.searchQuery =@"item 123";
event.customData =(NSMutableDictionary*)@{@"Custom_Event_Property_Key1":@"Custom_Event_Property_val1",@"Custom_Event_Property_Key2":@"Custom_Event_Property_val2"};// Log the event[event logEvent];
Objective-C
// Create a BranchUniversalObject with your content dataBranchUniversalObject buo =newBranchUniversalObject().setCanonicalIdentifier("myprod/1234").setCanonicalUrl("https://test_canonical_url").setTitle("test_title").setContentMetadata(newContentMetadata().addCustomMetadata("custom_metadata_key1","custom_metadata_val1").addCustomMetadata("custom_metadata_key1","custom_metadata_val1").addImageCaptions("image_caption_1","image_caption2","image_caption3").setAddress("Street_Name","test city","test_state","test_country","test_postal_code").setRating(5.2,6.0,5).setLocation(-151.67,-124.0).setPrice(10.0,CurrencyType.USD).setProductBrand("test_prod_brand").setProductCategory(ProductCategory.APPAREL_AND_ACCESSORIES).setProductName("test_prod_name").setProductCondition(ContentMetadata.CONDITION.EXCELLENT).setProductVariant("test_prod_variant").setQuantity(1.5).setSku("test_sku").setContentSchema(BranchContentSchema.COMMERCE_PRODUCT)).addKeyWord("keyword1").addKeyWord("keyword2");// Create an eventnewBranchEvent(BRANCH_STANDARD_EVENT.ADD_TO_CART).setAffiliation("test_affiliation").setCustomerEventAlias("my_custom_alias").setCoupon("Coupon Code").setCurrency(CurrencyType.USD).setDescription("Customer added item to cart").setShipping(0.0).setTax(9.75).setRevenue(1.5).setSearchQuery("Test Search query").addCustomDataProperty("Custom_Event_Property_Key1","Custom_Event_Property_val1").addCustomDataProperty("Custom_Event_Property_Key2","Custom_Event_Property_val2").addContentItems(buo)// Add a BranchUniversalObject to the event (cannot be empty).logEvent(context);// Log the event
Java
// Create a BranchUniversalObject with your content dataval buo =BranchUniversalObject().setCanonicalIdentifier("myprod/1234").setCanonicalUrl("https://test_canonical_url").setTitle("test_title").setContentMetadata(ContentMetadata().addCustomMetadata("custom_metadata_key1","custom_metadata_val1").addCustomMetadata("custom_metadata_key1","custom_metadata_val1").addImageCaptions("image_caption_1","image_caption2","image_caption3").setAddress("Street_Name","test city","test_state","test_country","test_postal_code").setRating(5.2,6.0,5).setLocation(-151.67,-124.0).setPrice(10.0, CurrencyType.USD).setProductBrand("test_prod_brand").setProductCategory(ProductCategory.APPAREL_AND_ACCESSORIES).setProductName("test_prod_name").setProductCondition(ContentMetadata.CONDITION.EXCELLENT).setProductVariant("test_prod_variant").setQuantity(1.5).setSku("test_sku").setContentSchema(BranchContentSchema.COMMERCE_PRODUCT)).addKeyWord("keyword1").addKeyWord("keyword2")// Create an eventBranchEvent(BRANCH_STANDARD_EVENT.ADD_TO_CART).setAffiliation("test_affiliation").setCustomerEventAlias("my_custom_alias").setCoupon("Coupon Code").setCurrency(CurrencyType.USD).setDescription("Customer added item to cart").setShipping(0.0).setTax(9.75).setRevenue(1.5).setSearchQuery("Test Search query").addCustomDataProperty("Custom_Event_Property_Key1","Custom_Event_Property_val1").addCustomDataProperty("Custom_Event_Property_Key2","Custom_Event_Property_val2").addContentItems(buo)// Add a BranchUniversalObject to the event (cannot be empty).logEvent(applicationContext)// Log the event
Kotlin
// Define event datavar event_and_custom_data ={"transaction_id":"tras_Id_1232343434","currency":"USD","revenue":180.2,"shipping":10.5,"tax":13.5,"coupon":"promo-1234","affiliation":"high_fi","description":"Preferred purchase","purchase_loc":"Palo Alto","store_pickup":"unavailable"};// Define content datavar content_items =[{"$content_schema":"COMMERCE_PRODUCT","$og_title":"Nike Shoe","$og_description":"Start loving your steps","$og_image_url":"http://example.com/img1.jpg","$canonical_identifier":"nike/1234","$publicly_indexable":false,"$price":101.2,"$locally_indexable":true,"$quantity":1,"$sku":"1101123445","$product_name":"Runner","$product_brand":"Nike","$product_category":"SPORTING_GOODS","$product_variant":"XL","$rating_average":4.2,"$rating_count":5,"$rating_max":2.2,"$creation_timestamp":1499892854966,"$exp_date":1499892854966,"$keywords":["sneakers","shoes"],"$address_street":"230 South LaSalle Street","$address_city":"Chicago","$address_region":"IL","$address_country":"US","$address_postal_code":"60604","$latitude":12.07,"$longitude":-97.5,"$image_captions":["my_img_caption1","my_img_caption_2"],"$condition":"NEW","$custom_fields":{"foo1":"bar1","foo2":"bar2"}},{"$og_title":"Nike Woolen Sox","$canonical_identifier":"nike/5324","$og_description":"Fine combed woolen sox for those who love your foot","$publicly_indexable":false,"$price":80.2,"$locally_indexable":true,"$quantity":5,"$sku":"110112467","$product_name":"Woolen Sox","$product_brand":"Nike","$product_category":"Apparel & Accessories","$product_variant":"Xl","$rating_average":3.3,"$rating_count":5,"$rating_max":2.8,"$creation_timestamp":1499892854966}];// Set aliasvar customer_event_alias ="my custom alias";// Log the event
branch.logEvent("PURCHASE",
event_and_custom_data,
content_items,
customer_event_alias,function(err){ console.log(err);});
JavaScript
// Create a BranchUniversalObjectlet buo =await branch.createBranchUniversalObject("item/12345",{
canonicalUrl:"https://branch.io/item/12345",
title:"My Item Title",
contentMetadata:{
quantity:1,
price:23.20,
sku:"1994320302",
productName:"my_product_name1",
productBrand:"my_prod_Brand1",
customMetadata:{
custom_key1:"custom_value1",
custom_key2:"custom_value2"}}})// Define content datalet params ={
transaction_id:"tras_Id_1232343434",
currency:"USD",
revenue:180.2,
shipping:10.5,
tax:13.5,
coupon:"promo-1234",
affiliation:"high_fi",
description:"Preferred purchase",
purchase_loc:"Palo Alto",
store_pickup:"unavailable",
customData:{"Custom_Event_Property_Key1":"Custom_Event_Property_val1","Custom_Event_Property_Key2":"Custom_Event_Property_val2"}}// Create an event and associate the BranchUniversalObject with itlet event =newBranchEvent(BranchEvent.Purchase,[buo], params)// Log the event
event.logEvent()
Content Events are events that occur when a user engages with your in-app content.
An example could be in-app articles that you post. In that instance, you might want to track events related to users performing search queries, viewing content, rating the content, and sharing it.
Content Events can relate to a wide variety of in-app content, such as blog posts, music, videos, pictures, and e-commerce catalogue items.
Event Name
iOS
Android
Web/API
Search
BranchStandardEventSearch
BRANCH_STANDARD_EVENT.SEARCH
SEARCH
View Item
BranchStandardEventViewItem
BRANCH_STANDARD_EVENT.VIEW_ITEM
VIEW_ITEM
View Items
BranchStandardEventViewItems
BRANCH_STANDARD_EVENT.VIEW_ITEMS
VIEW_ITEMS
Rate
BranchStandardEventRate
BRANCH_STANDARD_EVENT.RATE
RATE
Share
BranchStandardEventShare
BRANCH_STANDARD_EVENT.SHARE
SHARE
Initiate Stream
BranchStandardEventInitiateStream
BRANCH_STANDARD_EVENT.INITIATE_STREAM
INITIATE_STREAM
Complete Stream
BranchStandardEventCompleteStream
BRANCH_STANDARD_EVENT.COMPLETE_STREAM
COMPLETE_STREAM
Examples
// Create eventlet event =BranchEvent.standardEvent(.search)// Define event data
event.alias ="my custom alias"
event.eventDescription ="Product Search"
event.searchQuery ="user search query terms for product xyz"
event.customData["Custom_Event_Property_Key1"]="Custom_Event_Property_val1"// Log the event
event.logEvent()
Lifecycle Events are related to actions the user takes in your app to continue progressing through it. These events can apply to game apps as well as non-game apps. Examples include a user completing a tutorial, opting in to an email list, or starting a free trial.
If you are sending any event to Branch via a server to server call and you are running Facebook campaigns on iOS, it is required that you send the OS version to Branch for proper attribution on Facebook ads.
Testing
To make sure your events are being sent to Branch, you can check the Liveview page of the Branch Dashboard.
Please note that it may take several minutes for your events to appear in Liveview after they've been triggered.