Track Commerce, Content, Lifecycle and Custom Events
V1 Events
Branch will be removing support for our v1 Events API endpoint on September 4, 2023. The v1 Events API endpoint will no longer function after this date and this will impact your app experience. Branch highly recommends you update your app with the latest version to avoid any impact to your app experience.
Please confirm which version you have installed in your app. If your app is utilizing the following methods to track events, please update the version and use our current methods that we guide here.
sendCommerceEvent()
userCompletedAction()
Branch.track()
Overview
By default, Branch mobile SDKs track clicks, opens, installs, reinstalls and impressions automatically (out-of-the-box).
Similarly, the Branch Web SDK tracks pageviews, web session starts, clicks, and impressions automatically (out-of-the-box).
Branch has also standardized the way "classes" of events are tracked. For example: all events related to a customer purchase are bucketed into a "purchase" class of data items, and all events related to a user interacting with your in-app content are linked to a "content" class of data items.
This page offers a breakdown of the different classes of events and includes examples on how to track them using the Branch SDKs.
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.
Events for Optimization
When Universal Ads is enabled, tracking these events will postback to the attributed Ad Network. For example, if you track the purchase event through Branch, this 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, so you can understand their performance even when using SafeTrack Attribution.
Available Events
Event Tracking Disclaimer
Branch may implement caps/overages on the number of events you are tracking. We recommend that you only track events that are useful for your analytics and attribution needs. Additionally, this will avoid unnecessary network calls that your app will make leading to better app performance.
Facebook Ads Support
If you are sending any event Server to Server to Branch and are running Facebook campaigns on iOS, it is required to send the OS version for Branch to provide attribution on Facebook ads.
Commerce Events
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 |
Content Events
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 |
Lifecycle Events
Event Name | iOS | Android | Web/API |
---|---|---|---|
Complete Registration | BranchStandardEventCompleteRegistration | BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION | COMPLETE_REGISTRATION |
Complete Tutorial | BranchStandardEventCompleteTutorial | BRANCH_STANDARD_EVENT.COMPLETE_TUTORIAL | COMPLETE_TUTORIAL |
Achieve Level | BranchStandardEventAchieveLevel | BRANCH_STANDARD_EVENT.ACHIEVE_LEVEL | ACHIEVE_LEVEL |
Unlock Achievement | BranchStandardEventUnlockAchievement | BRANCH_STANDARD_EVENT.UNLOCK_ACHIEVEMENT | UNLOCK_ACHIEVEMENT |
Invite | BranchStandardEventInvite | BRANCH_STANDARD_EVENT.INVITE | INVITE |
Login | BranchStandardEventLogin | BRANCH_STANDARD_EVENT.LOGIN | LOGIN |
Start Trial | BranchStandardEventStartTrial | BRANCH_STANDARD_EVENT.START_TRIAL | START_TRIAL |
Subscribe | BranchStandardEventSubscribe | BRANCH_STANDARD_EVENT.SUBSCRIBE | SUBSCRIBE |
Opt In | Tracked via handleATTAuthorizationStatus() | Not Applicable | Not Applicable |
Opt Out | Tracked via handleATTAuthorizationStatus() | Not Applicable | Not Applicable |
Custom Events
Custom Events can be tracked if the event does not fall within one of the categories above.
Note: Custom data in the Branch dashboard is viewable in Liveview and Exports.
Track Commerce Events
Commerce events describe events that relate to a customer interacting with your products and converting by purchasing. These are events like adding payment information, purchasing, viewing products, etc. If you have enabled Branch Universal Ads, these events will automatically map to certain Ad Partners. Start by creating a Branch Universal Object for each product that is associated with the event you're tracking.
From there, add the Branch universal object to the tracked event, and use the right predefined constant. For example, the code snippet below is to track when a user adds to cart, but simply replace that constant with another constant to track a different event.
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.
Currency and Exchange Rates
If you track commerce events without a currency, we assume they are 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.
HTTP API - Commerce Endpoint
POST /v2/event/standard
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
Product Category Options
// Values available for the `productCategory` field
ANIMALS_AND_PET_SUPPLIES("Animals & Pet Supplies"),
APPAREL_AND_ACCESSORIES("Apparel & Accessories"),
ARTS_AND_ENTERTAINMENT("Arts & Entertainment"),
BABY_AND_TODDLER("Baby & Toddler"),
BUSINESS_AND_INDUSTRIAL("Business & Industrial"),
CAMERAS_AND_OPTICS("Cameras & Optics"),
ELECTRONICS("Electronics"),
FOOD_BEVERAGES_AND_TOBACCO("Food, Beverages & Tobacco"),
FURNITURE("Furniture"),
HARDWARE("Hardware"),
HEALTH_AND_BEAUTY("Health & Beauty"),
HOME_AND_GARDEN("Home & Garden"),
LUGGAGE_AND_BAGS("Luggage & Bags"),
MATURE("Mature"),
MEDIA("Media"),
OFFICE_SUPPLIES("Office Supplies"),
RELIGIOUS_AND_CEREMONIAL("Religious & Ceremonial"),
SOFTWARE("Software"),
SPORTING_GOODS("Sporting Goods"),
TOYS_AND_GAMES("Toys & Games"),
VEHICLES_AND_PARTS("Vehicles & Parts")
Example - Commerce Tracking
// Create a BranchUniversalObject with your content data:
let 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 a BranchEvent:
let 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"
]
event.logEvent() // Log the event.
// 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 and add the BranchUniversalObject to it.
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventAddToCart];
// Add the BranchUniversalObjects 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"
};
[event logEvent];
BranchUniversalObject buo = new BranchUniversalObject()
.setCanonicalIdentifier("myprod/1234")
.setCanonicalUrl("https://test_canonical_url")
.setTitle("test_title")
.setContentMetadata(
new 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");
// Do not add an empty branchUniversalObject to the BranchEvent
new BranchEvent(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)
.logEvent(context);
val 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")
// Do not add an empty branchUniversalObject to the BranchEvent
BranchEvent(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)
.logEvent(applicationContext)
let 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"
}
}
}
)
let 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"
}
}
let event = new BranchEvent(BranchEvent.Purchase, [buo], params)
event.logEvent()
BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.PURCHASE);
event.transactionID = "12344555";
event.currency = BranchCurrencyType.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.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1');
event.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContent(buo: [buo], branchEvent: event);
var 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"
};
var 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
}];
var customer_event_alias = "my custom alias";
branch.logEvent(
"PURCHASE",
event_and_custom_data,
content_items,
customer_event_alias,
function(err) { console.log(err); }
);
// Create a BranchUniversalObject with your content data:
let 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 a BranchEvent:
let event = BranchEvent.standardEvent(.purchase)
// Add the BranchUniversalObject with the content (do not add an empty branchUniversalObject):
event.contentItems = [ branchUniversalObject ]
// Add relevant event data:
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"
]
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
// 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.0;
branchUniversalObject.contentMetadata.price = [NSDecimalNumber decimalNumberWithString:@"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 and add the BranchUniversalObject to it.
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventAddToCart];
// Add the BranchUniversalObjects with the content (do not add an empty branchUniversalObject):
event.contentItems = (id) @[ branchUniversalObject ];
// Add relevant event data:
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"
};
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
"name": "PURCHASE",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": "25",
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"purchase_loc": "Palo Alto",
"store_pickup": "unavailable"
},
"event_data": {
"transaction_id": "trans_Id_1232343434",
"currency": "USD",
"revenue": 180.2,
"shipping": 10.5,
"tax": 13.5,
"coupon": "promo-1234",
"affiliation": "high_fi",
"description": "Preferred purchase",
"custom_param_1": "Parameter 1",
"custom_param_2": "Parameter 2",
"custom_param_3": "Parameter 3"
},
"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
}
],
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard
BranchEvent branchEvent = new BranchEvent(BranchEventType.PURCHASE);
branchEvent.AddCustomData("Transaction ID", "12344555");
branchEvent.AddCustomData("Currency", BranchCurrencyType.USD.ToString());
branchEvent.AddCustomData("Revenue", "1.5");
branchEvent.AddCustomData("Shipping", "10.2");
branchEvent.AddCustomData("Tax", "12.3");
branchEvent.AddCustomData("Coupon", "test_coupon");
branchEvent.AddCustomData("Affiliation", "test_affiliation");
branchEvent.AddCustomData("Event Description", "event_description");
branchEvent.AddCustomData("Search Query", "item 123");
branchEvent.AddCustomData("Custom_Event_Property_Key1", "Custom_Event_Property_val1");
branchEvent.AddCustomData("Custom_Event_Property_Key2", "Custom_Event_Property_val2");
Branch.sendEvent(branchEvent);
See full API docs here.
Track Content Events
Content events are events that occur when a user engages with your in-app content. For example, if you have in-app articles, you would want to track events related to when users search, view content, rate the content, and share. This can apply to a wide variety of in-app content, such as blog posts, music, video, pictures, and e-commerce catalogue items.
HTTP API - Content Endpoint
POST /v2/event/standard
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
Example - Content Tracking
let event = BranchEvent.standardEvent(.search)
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"
event.logEvent()
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventSearch];
event.alias = @"my custom alias";
event.eventDescription = @"Product Search";
event.searchQuery = @"user search query terms for product xyz";
event.customData = (NSMutableDictionary*) @{
@"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
@"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
};
new BranchEvent(BRANCH_STANDARD_EVENT.SEARCH)
.setCustomerEventAlias("my_custom_alias")
.setDescription("Product Search")
.setSearchQuery("product name")
.addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
.logEvent(context);
BranchEvent(BRANCH_STANDARD_EVENT.SEARCH)
.setCustomerEventAlias("my_custom_alias")
.setDescription("Product Search")
.setSearchQuery("product name")
.addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
.logEvent(applicationContext);
let params = {
alias: "my custom alias",
description: "Product Search",
searchQuery: "user search query terms for product xyz",
customData: {
"Custom_Event_Property_Key1": "Custom_Event_Property_val1",
"Custom_Event_Property_Key2": "Custom_Event_Property_val2"
}
}
let event = new BranchEvent(BranchEvent.Search, null, params)
event.logEvent()
BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.SEARCH);
event.eventDescription = "Product Search";
event.searchQuery = "user search query terms for product xyz";
event.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1');
event.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContentWithoutBuo(branchEvent: event);
var 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"
};
var 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
}];
var customer_event_alias = "my custom alias";
branch.logEvent(
"VIEW_ITEMS",
event_and_custom_data,
content_items,
customer_event_alias,
function(err) { console.log(err); }
);
// Create a BranchEvent:
let event = BranchEvent.standardEvent(.search)
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"
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventSearch];
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";
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
"name": "VIEW_ITEMS",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": "25",
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"purchase_loc": "Palo Alto",
"store_pickup": "unavailable"
},
"event_data": {
"search_query": "red sneakers",
"description": "Preferred purchase",
"custom_param_1": "Parameter 1",
"custom_param_2": "Parameter 2",
"custom_param_3": "Parameter 3"
},
"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,
"$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,
"$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
}
],
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard
BranchEvent branchEvent = new BranchEvent(BranchEventType.SEARCH);
branchEvent.SetAlias("my_custom_alias");
branchEvent.AddCustomData("Description", "Product Search");
branchEvent.AddCustomData("Search Query", "product name");
branchEvent.AddCustomData("Custom_Event_Property_Key1", "Custom_Event_Property_val1");
Branch.sendEvent(branchEvent);
See full API docs here.
Track Lifecycle Events
Lifecycle events can be described as events a user takes in your app to continue progressing. These events can apply to game apps, as well as non game apps, for when a user completes a user profile, registration or tutorial.
HTTP API - Lifecycle Endpoint
POST /v2/event/standard
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
Example - Lifecycle Tracking
let event = BranchEvent.standardEvent(.completeRegistration)
event.alias = "my custom alias"
event.transactionID = "tx1234"
event.eventDescription = "User completed registration."
event.customData["registrationID"] = "12345"
event.logEvent()
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventCompleteRegistration];
event.alias = "my custom alias";
event.transactionID = @"tx1234";
event.eventDescription = @"User completed registration.";
event.customData = (NSMutableDictionary*) @{
@"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
@"Custom_Event_Property_Key2": @"Custom_Event_Property_val2",
@"registrationID": @"12345"
};
[event logEvent];
new BranchEvent(BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION)
.setCustomerEventAlias("my_custom_alias")
.setTransactionID("tx1234")
.setDescription("User created an account")
.addCustomDataProperty("registrationID", "12345")
.logEvent(context);
BranchEvent(BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION)
.setCustomerEventAlias("my_custom_alias")
.setTransactionID("tx1234")
.setDescription("User created an account")
.addCustomDataProperty("registrationID", "12345")
.logEvent(applicationContext);
let params = {
alias: "my custom alias",
transaction_id: "tras_Id_1234",
description: "Preferred purchase",
registration_id: "12345",
customData: {
"Custom_Event_Property_Key1": "Custom_Event_Property_val1",
"Custom_Event_Property_Key2": "Custom_Event_Property_val2"
}
}
let event = new BranchEvent(BranchEvent.CompleteRegistration, null, params)
event.logEvent()
BranchEvent event = BranchEvent.standardEvent(BranchStandardEvent.COMPLETE_REGISTRATION);
event.transactionID = "tx1234";
event.eventDescription = "User completed registration";
event.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1');
event.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContentWithoutBuo(branchEvent: event);
var event_and_custom_data = {
"transaction_id": "tras_Id_1234",
"description": "Preferred purchase",
"registration_id": "12345"
};
var customer_event_alias = "my custom alias";
branch.logEvent(
"COMPLETE_REGISTRATION",
event_and_custom_data,
customer_event_alias,
function(err) { console.log(err); }
);
// Create a BranchEvent:
let event = BranchEvent.standardEvent(.completeRegistration)
event.alias = "my custom alias"
event.transactionID = "tx1234"
event.eventDescription = "User completed registration."
event.customData["registrationID"] = "12345"
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventCompleteRegistration];
event.alias = "my custom alias";
event.transactionID = @"tx1234";
event.eventDescription = @"User completed registration.";
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
"name": "COMPLETE_REGISTRATION",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": "25",
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"foo": "bar"
},
"event_data": {
"description": "Preferred purchase",
"custom_param_1": "Parameter 1",
"custom_param_2": "Parameter 2",
"custom_param_3": "Parameter 3"
},
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard
BranchEvent branchEvent = new BranchEvent(BranchEventType.COMPLETE_REGISTRATION);
branchEvent.SetAlias("my_custom_alias");
branchEvent.AddCustomData("Transaction_ID", "tx1234");
branchEvent.AddCustomData("Description", "User created an account");
branchEvent.AddCustomData("registrationID", "12345");
Branch.sendEvent(branchEvent);
See full API docs here.
Track Custom Events
If you want to track an event that isn't a predefined event, simply do the following:
Custom Event Names
The name
custom event
is reserved by Branch. Please ensure you give your custom event an actual name.Additionally, do not use the same name for your custom event as Standard Events. This will have an impact on attribution with Self-Attributing Networks and event mapping.
We strongly recommend using custom event names that contain no more than 40 characters, contain only letters, numbers, hyphens, spaces, and underscores, and do not start with a hyphen. Facebook will not accept events that violate these rules, and if you enable the Facebook integration, Branch may sanitize your event names to pass validation.
HTTP API - Custom Endpoint
POST /v2/event/custom
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
Example - Custom Tracking
let event = BranchEvent.customEvent(withName:"User_Scanned_Item")
event.customData["Custom_Event_Property_Key1"] = "Custom_Event_Property_val1"
event.customData["Custom_Event_Property_Key2"] = "Custom_Event_Property_val2"
event.alias = "my custom alias"
event.logEvent()
BranchEvent *event = [BranchEvent customEventWithName:@"User_Scanned_Item"];
event.customData = (NSMutableDictionary*) @{
@"Custom_Event_Property_Key1": @"Custom_Event_Property_val1",
@"Custom_Event_Property_Key2": @"Custom_Event_Property_val2"
};
event.alias = "my custom alias";
[event logEvent];
new BranchEvent("Some Custom Event")
.addCustomDataProperty("Custom_Event_Property_Key11", "Custom_Event_Property_val11")
.addCustomDataProperty("Custom_Event_Property_Key22", "Custom_Event_Property_val22")
.setCustomerEventAlias("my_custom_alias")
.logEvent(MainActivity.this);
BranchEvent("Some Custom Event")
.addCustomDataProperty("Custom_Event_Property_Key11", "Custom_Event_Property_val11")
.addCustomDataProperty("Custom_Event_Property_Key22", "Custom_Event_Property_val22")
.setCustomerEventAlias("my_custom_alias")
.logEvent(this);
let params = {
alias: "my custom alias",
customData: {
"Custom_Event_Property_Key1": "Custom_Event_Property_val1",
"Custom_Event_Property_Key2": "Custom_Event_Property_val2"
}
}
let event = new BranchEvent("Some Custom Event", null, params) //pass null if no BranchUniversalObject is used
event.logEvent()
BranchEvent eventCustom = BranchEvent.customEvent('User_Scanned_Item');
eventCustom.addCustomData('Custom_Event_Property_Key1', 'Custom_Event_Property_val1')
eventCustom.addCustomData('Custom_Event_Property_Key2', 'Custom_Event_Property_val2');
FlutterBranchSdk.trackContentWithoutBuo(branchEvent: eventCustom);
var custom_data = {
"Custom_Event_Property_Key1": "Custom_Event_Property_val1",
"Custom_Event_Property_Key2": "Custom_Event_Property_val2"
};
branch.logEvent(
'custom_event_name',
custom_data,
function(err) { console.log(err); }
);
// Create a BranchEvent:
let event = BranchEvent.customEvent(withName:"User_Scanned_Item")
event.customData["Custom_Event_Property_Key1"] = "Custom_Event_Property_val1"
event.customData["Custom_Event_Property_Key2"] = "Custom_Event_Property_val2"
event.alias = "my custom alias"
// The log method is on the Branch singleton instead of the event object
Branch.sharedInstance.logEvent(event) { (error) in
// log error here
}
BranchEvent *event = [BranchEvent customEventWithName:@"User_Scanned_Item"];
event.customData[@"Custom_Event_Property_Key1"] = @"Custom_Event_Property_val1";
event.customData[@"Custom_Event_Property_Key2"] = @"Custom_Event_Property_val2";
event.alias = "my custom alias";
[[Branch sharedInstance] logEvent:event completion:^(NSError * _Nullable error) {
NSLog(@"Test Standard Event: %@", error);
}];
curl -vvv -d '{
"name": "picture swiped",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": "25",
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"event_data": {
"custom_param_1": "Parameter 1",
"custom_param_2": "Parameter 2",
"custom_param_3": "Parameter 3"
},
"custom_data": {
"foo": "bar"
},
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/custom
BranchEvent branchEvent = new BranchEvent("Some Custom Event");
branchEvent.AddCustomData("Custom_Event_Property_Key11", "Custom_Event_Property_val11");
branchEvent.AddCustomData("Custom_Event_Property_Key22", "Custom_Event_Property_val22");
branchEvent.SetAlias("my_custom_alias");
Branch.sendEvent(branchEvent);
See full API docs here.
Testing Events
In order to test whether v2/events are being received on Branch's backend, check out Liveview.
Updated 3 months ago