Developers Hub

Tracking Commerce, Content, Lifecycle and Custom Events

Suggest Edits

Overview

It's always been possible to track events with the Branch SDK, including installs, opens, purchases, and more. Now we're introducing a new way to track events that make reporting and analytics a whole lot better and easier.

The new v2 events have better tracking and analytics options in the Branch dashboard, and the new event structure makes integration with third party analytics providers quicker and tighter.

We're standardizing 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 Exports.

Available Events

Use the table below to quickly find the event you want to track.

Event Name Event Category iOS Android Web and API
Add To Cart Commerce Event BranchStandardEventAddToCart BRANCH_STANDARD_EVENT.ADD_TO_CART ADD_TO_CART
Add To Wishlist Commerce Event BranchStandardEventAddToWishlist BRANCH_STANDARD_EVENT.ADD_TO_WISHLIST ADD_TO_WISHLIST
View Cart Commerce Event BranchStandardEventViewCart BRANCH_STANDARD_EVENT.VIEW_CART VIEW_CART
Initiate Purchase Commerce Event BranchStandardEventInitiatePurchase BRANCH_STANDARD_EVENT.INITIATE_PURCHASE INITIATE_PURCHASE
Add Payment Info Commerce Event BranchStandardEventAddPaymentInfo BRANCH_STANDARD_EVENT.ADD_PAYMENT_INFO ADD_PAYMENT_INFO
Click Ad Commerce Event BranchStandardEventClickAd BRANCH_STANDARD_EVENT.CLICK_AD CLICK_AD
Purchase Commerce Event BranchStandardEventPurchase BRANCH_STANDARD_EVENT.PURCHASE PURCHASE
Spend Credits Commerce Event BranchStandardEventSpendCredits BRANCH_STANDARD_EVENT.SPEND_CREDITS SPEND_CREDITS
Start Trial Lifecycle Event BranchStandardEventStartTrial BRANCH_STANDARD_EVENT.START_TRIAL START_TRIAL
Subscribe Lifecycle Event BranchStandardEventSubscribe BRANCH_STANDARD_EVENT.SUBSCRIBE SUBSCRIBE
View Ad Commerce Event BranchStandardEventViewAd BRANCH_STANDARD_EVENT.VIEW_AD VIEW_AD
Search Content Event BranchStandardEventSearch BRANCH_STANDARD_EVENT.SEARCH SEARCH
View Item Content Event BranchStandardEventViewItem BRANCH_STANDARD_EVENT.VIEW_ITEM VIEW_ITEM
View Items Content Event BranchStandardEventViewItems BRANCH_STANDARD_EVENT.VIEW_ITEMS VIEW_ITEMS
Rate Content Event BranchStandardEventRate BRANCH_STANDARD_EVENT.RATE RATE
Share Content Event BranchStandardEventShare BRANCH_STANDARD_EVENT.SHARE SHARE
Complete Registration Lifecycle Event BranchStandardEventCompleteRegistration BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION COMPLETE_REGISTRATION
Complete Tutorial Lifecycle Event BranchStandardEventCompleteTutorial BRANCH_STANDARD_EVENT.COMPLETE_TUTORIAL COMPLETE_TUTORIAL
Achieve Level Lifecycle Event BranchStandardEventAchieveLevel BRANCH_STANDARD_EVENT.ACHIEVE_LEVEL ACHIEVE_LEVEL
Unlock Achievement Lifecycle Event BranchStandardEventUnlockAchievement BRANCH_STANDARD_EVENT.UNLOCK_ACHIEVEMENT UNLOCK_ACHIEVEMENT
Invite Lifecycle Event BranchStandardEventInvite BRANCH_STANDARD_EVENT.INVITE INVITE
Login Lifecycle Event BranchStandardEventLogin BRANCH_STANDARD_EVENT.LOGIN LOGIN
Reserve Lifecycle Event BranchStandardEventReserve BRANCH_STANDARD_EVENT.RESERVE RESERVE

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); }
);

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(
    event,
    custom_data,
    callback (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 7 days ago

Tracking Commerce, Content, Lifecycle and Custom Events

Suggested Edits are limited on API Reference Pages

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