Overview
By default, the Branch SDK tracks 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).
We've also standardized the way you track "classes" of events. For example: all events related to a customer purchasing are bucketed into a "purchase" class of data items, and all events related to users interacting with your in-app content are linked to a "content" class of data items.
Below are examples of the kinds of events you'll likely be interested in tracking, and we'll show you the way to track through our SDKs.
Acceptance
Tracking these events will propagate to Ad Networks, like Criteo. For example, if you track the purchase event through Branch, this will map to Criteo's Purchase event.
These events will also have analytics, so you can understand their performance, using the new People-Based Attribution.
Limitations
As of now, any calls made through these SDK methods will not:
- Work with our referrals system.
- Show custom data in the Branch dashboard aside from Liveview and Exports.
Available 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 |
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 |
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 |
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 |
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.
A note on 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 realtime exchange rate. If you view raw Branch events via either Webhooks or Exports, you can see the exchange rate used.
iOS - Commerce
// 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 = 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];
Android - Commerce
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);
Web - Commerce
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); }
);
macOS
// 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);
}];
HTTP API - Commerce
Endpoint
POST /v2/event/standard
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
developer_identity OR
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
curl -vvv -d '{
"name": "PURCHASE",
"customer_event_alias": "my custom alias",
"user_data": {
"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"
},
"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
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.
iOS - Content
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[@"Custom_Event_Property_Key1"] = @"Custom_Event_Property_val1";
[event logEvent];
Android - Content
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);
Web - Content
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); }
);
HTTP API - Content
Endpoint
POST /v2/event/standard
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
developer_identity OR
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
curl -vvv -d '{
"name": "VIEW_ITEMS",
"customer_event_alias": "my custom alias",
"user_data": {
"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"
},
"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
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.
iOS - Lifecycle
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[@"registrationID"] = @"12345";
[event logEvent];
Android - Lifecycle
new BranchEvent(BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION)
.setCustomerEventAlias("my_custom_alias")
.setTransactionID("tx1234")
.setDescription("User created an account")
.addCustomDataProperty("registrationID", "12345")
.logEvent(context);
Web - Lifecycle
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,
content_items,
customer_event_alias,
function(err) { console.log(err); }
);
HTTP API - Lifecycle
Endpoint
POST /v2/event/standard
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
developer_identity OR
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
curl -vvv -d '{
"name": "COMPLETE_REGISTRATION",
"customer_event_alias": "my custom alias",
"user_data": {
"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"
},
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard
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.
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.
iOS - Custom
let 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"
event.logEvent()
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";
[event logEvent];
Android - Custom
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);
Web - Custom
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); }
);
HTTP API - Custom
Endpoint
POST /v2/event/custom
Content-Type: application/json
Parameters
Note about required identifiers. You must send up (in user_data):
developer_identity OR
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)
curl -vvv -d '{
"name": "picture swiped",
"customer_event_alias": "my custom alias",
"user_data": {
"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"
},
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/custom
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 23 days ago