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 SafeTrack 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 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.

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

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
Opt In	Tracked via handleATTAuthorizationStatus()	Not Applicable	Not Applicable
Opt Out	Tracked via handleATTAuthorizationStatus()	Not Applicable	Not Applicable

Custom Events can be tracked if the event does not fall within one of the categories above.

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             = [[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];

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):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

🚧
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.

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):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

🚧
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.

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):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

🚧
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.

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):

browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

🚧
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.

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.

Developers Hub

Track Commerce, Content, Lifecycle and Custom Events

Overview

Acceptance

Limitations

Available Events

🚧
Event Tracking Disclaimer

Track Commerce Events

iOS - Commerce

Android - Commerce

Web - Commerce

macOS

HTTP API - Commerce

🚧
Facebook Ads Support

Track Content Events

iOS - Content

Android - Content

Web - Content

HTTP API - Content

🚧
Facebook Ads Support

Track Lifecycle Events

iOS - Lifecycle

Android - Lifecycle

Web - Lifecycle

HTTP API - Lifecycle

🚧
Facebook Ads Support

Track Custom Events

🚧
Custom Event Names

iOS - Custom

Android - Custom

Web - Custom

HTTP API - Custom

🚧
Facebook Ads Support

Testing Events

Track Commerce, Content, Lifecycle and Custom Events

Suggested Edits are limited on API Reference Pages

Overview

Acceptance

Limitations

Available Events

🚧Event Tracking Disclaimer

Track Commerce Events

iOS - Commerce

Android - Commerce

Web - Commerce

macOS

HTTP API - Commerce

🚧Facebook Ads Support

Track Content Events

iOS - Content

Android - Content

Web - Content

HTTP API - Content

🚧Facebook Ads Support

Track Lifecycle Events

iOS - Lifecycle

Android - Lifecycle

Web - Lifecycle

HTTP API - Lifecycle

🚧Facebook Ads Support

Track Custom Events

🚧Custom Event Names

iOS - Custom

Android - Custom

Web - Custom

HTTP API - Custom

🚧Facebook Ads Support

Testing Events

Filters

🚧
Event Tracking Disclaimer

🚧
Facebook Ads Support

🚧
Facebook Ads Support

🚧
Facebook Ads Support

🚧
Custom Event Names

🚧
Facebook Ads Support