

V2 Event

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.

Prerequisites

With event tracking, it's important to track the objects related to the event occurring. Branch provides a class to describe your in-app content items called the Branch Universal Object. For any of the events tracked below, make sure to include the universal object(s) involved. For example, if you want to track when someone purchases 3 items, you'd want to create a Branch Universal Object per item, and pass them along when tracking the event.

Refer to the above document to set up Branch Universal Objects.

Current Compatibility

There are a few products and features unsupported by this new method of tracking events. We clarify what's currently supported and what isn't below.

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

• See Analytics on the old Analytics pipeline. Read more about our new People-Based Attribution.
• Work with our referrals system.

Available Events

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

Event Name	Event Category	iOS	Android	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
Purchase	Commerce Event	BranchStandardEventPurchase	BRANCH_STANDARD_EVENT.PURCHASE	PURCHASE
Spend Credits	Commerce Event	BranchStandardEventSpendCredits	BRANCH_STANDARD_EVENT.SPEND_CREDITS	SPEND_CREDITS
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

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

• Swift

  // 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"
  
  // Create a BranchEvent:
  let event = BranchEvent.standardEvent(.purchase)
  
  // Add the BranchUniversalObjects with the content:
  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"
  ]
  event.logEvent() // Log the event.
  

• Objective-C

  // 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";
  
  // Create an event and add the BranchUniversalObject to it.
  BranchEvent *event     = [BranchEvent standardEvent:BranchStandardEventAddToCart];
  
  // Add the BranchUniversalObjects with the content:
  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"
  };
  [event logEvent];
  

Android

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

new BranchEvent(BRANCH_STANDARD_EVENT.ADD_TO_CART)
        .setAffiliation("test_affiliation")
        .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);

HTTP API

curl -vvv -d '{
  "name": "PURCHASE",
  "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",
    "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://api.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

• Swift

  let event = BranchEvent.standardEvent(.search)
  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()
  

• Objective-C

  BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventSearch];
  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

 new BranchEvent(BRANCH_STANDARD_EVENT.SEARCH)
    .setDescription("Product Search")
    .setSearchQuery("product name")
    .addCustomDataProperty("Custom_Event_Property_Key1", "Custom_Event_Property_val1")
    .logEvent(context);

HTTP API

curl -vvv -d '{
  "name": "VIEW_ITEMS",
  "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",
    "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://api.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

• Swift

  let event = BranchEvent.standardEvent(.completeRegistration)
  event.transactionID = "tx1234"
  event.eventDescription = "User completed registration."
  event.customData["registrationID"] = "12345"
  event.logEvent()
  

• Objective-C

  BranchEvent *event = [BranchEvent standardEvent:BranchStandardEventCompleteRegistration];
  event.transactionID = @"tx1234"
  event.eventDescription = @"User completed registration.";
  event.customData[@"registrationID"] = @"12345";
  [event logEvent];
  

Android

new BranchEvent(BRANCH_STANDARD_EVENT.COMPLETE_REGISTRATION)
    .setTransactionID("tx1234")
    .setDescription("User created an account")
    .addCustomDataProperty("registrationID", "12345")
    .logEvent(context);

HTTP

curl -vvv -d '{
  "name": "COMPLETE_REGISTRATION",
  "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",
    "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://api.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

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

• Swift

  BranchEvent.customEventWithName("User_Scanned_Item").logEvent()
  

• Objective-C

  [BranchEvent.customEventWithName(@"User_Scanned_Item") logEvent];
  

Android

new BranchEvent("Some Custom Event")
    .addCustomDataProperty("Custom_Event_Property_Key11", "Custom_Event_Property_val11")
    .addCustomDataProperty("Custom_Event_Property_Key22", "Custom_Event_Property_val22")
    .logEvent(MainActivity.this);
}

HTTP API

curl -vvv -d '{
  "name": "picture swiped",
  "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",
    "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://api.branch.io/v2/event/custom

See full API docs here.

Testing v2/event

In order to test whether v2/events are being received on Branch's backend, check out Liveview. Be sure you have opted into the new People-Based Attribution.