Try It!
Try out the Events API for your Branch App via the API reference here.
Overview
Branch's Events API is a robust endpoint for tracking all of your conversions in your app. With it, you'll be able to tie in detailed metadata about your Commerce, Content, Lifecycle, and Custom Events to better understand user behavior and attribute to your ongoing campaigns.
Prerequisites
In order to access the Events API, you need to have completed the following:
- Created a Branch Dashboard
Authentication
Calls to the Events API require your Branch Key parameter to be passed with each request. This can be obtained through the Branch Dashboard Account Settings.
Learn more about your Branch Account Profile here.
API Usage
Logging Standard Events - Commerce, Content, User Lifecycle
Endpoint
POST /v2/event/standard
Request Header Parameters
Parameter | Value | Required |
---|---|---|
Content-Type | application/json | Yes |
Request Body Parameters
Parameter | Description | Required |
---|---|---|
branch_key | The Branch key of the originating app; from your Branch Settings Dashboard | Yes |
name | The name of the event to log. Can be one of the following depending on which type of report you are running: Commerce: ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS Content: SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE User Lifecycle: ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS | Yes |
customer_event_alias | The event alias as defined by you; used in addition to the event name defined above. | No |
user_data.os | Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc. | Yes |
user_data.os_version | The version of the operating system. | No |
user_data.environment | usually FULL_APP | No |
user_data.aaid | The Android/Google advertising ID. | No |
user_data.android_id | Android hardware ID | No |
user_data.idfa | iOS advertising ID | No |
user_data.idfv | iOS vendor ID | No |
user_data.limit_ad_tracking | true if the partner has opted to not be tracked by advertisers | No |
user_data.user_agent | The user agent of the browser or app where the event occurred. Usually associated with a webview. | No |
user_data.browser_fingerprint_id | Branch internal-only field for tracking browsers. | No |
user_data.http_origin | The current page url where Web SDK logged web session start. | No |
user_data.http_referrer | The referral url that led to the current page where Web SDK logged web session start. | No |
user_data.developer_identity | The developer-specified identity for a user. | No |
user_data.country | The country code of the user, usually based on device settings or user agent string. | No |
user_data.language | The language code of the user, usually based on device settings or user agent string. | No |
user_data.ip | The ip address for the device where the event occurred | Yes |
user_data.local_ip | Android only : local ip of the device (e.g. "168.1.1.1") | No |
user_data.brand | The brand of the device | No |
user_data.randomized_device_token | Branch internal-only field for tracking devices. | No |
user_data.app_version | The app version downloaded by the user. | No |
user_data.model | The model of the device. | No |
user_data.screen_dpi | The screen's DPI. | No |
user_data.screen_height | The screen's height. | No |
user_data.screen_width | The screen's width. | No |
custom_data | The key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks. | No |
event_data.transaction_id | The partner-specified transaction id for their internal use | No |
event_data.revenue | The partner-specified reported revenue for the event. | No |
event_data.currency | Currency that revenue, price, shipping, tax were originally reported in by the partner | No |
event_data.shipping | Shipping cost associated with the transaction. | No |
event_data.tax | Total tax associated with the transaction. | No |
event_data.coupon | Transaction coupon redeemed with the transaction (e.g. "SPRING2017") | No |
event_data.affiliation | Store or affiliation from which this transaction occurred (e.g. Google Store) | No |
event_data.description | Description associated with the event, not necessarily specific to any individual content items (see below) | No |
content_items[i].$content_schema | Commerce and Content Reports only Category / Schema for a piece of content. May be used in the future for analytics. One of: COMMERCE_AUCTION COMMERCE_BUSINESS COMMERCE_OTHER COMMERCE_PRODUCT COMMERCE_RESTAURANT COMMERCE_SERVICE COMMERCE_TRAVEL_FLIGHT COMMERCE_TRAVEL_HOTEL COMMERCE_TRAVEL_OTHER GAME_STATE MEDIA_IMAGE MEDIA_MIXED MEDIA_MUSIC MEDIA_OTHER MEDIA_VIDEO OTHER TEXT_ARTICLE TEXT_BLOG TEXT_OTHER TEXT_RECIPE TEXT_REVIEW TEXT_SEARCH_RESULTS TEXT_STORY TEXT_TECHNICAL_DOC | No |
content_items[i].$og_title | Commerce and Content Reports only The title (for the individual content item). | No |
content_items[i].$og_image_url | Commerce and Content Reports only The image URL (for the individual content item). | No |
content_items[i].$canonical_identifier | Commerce and Content Reports only Used to allow Branch to unify content/messages for Content Analytics | No |
content_items[i].$publicly_indexable | Commerce and Content Reports onlytrue : content can be seen by anyonefalse : cannot index for public use | No |
content_items[i].$locally_indexable | Commerce and Content Reports onlytrue : content can be indexed for local (device) usefalse : cannot index for local use | No |
content_items[i].$price | Commerce and Content Reports only The price for the product/content. | No |
content_items[i].$quantity | Commerce and Content Reports only The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc). | No |
content_items[i].$sku | Commerce and Content Reports only The product sku or product ID. | No |
content_items[i].$product_name | Commerce and Content Reports only The product's name. | No |
content_items[i].$product_brand | Commerce and Content Reports only The product's brand. | No |
content_items[i].$product_category | Commerce and Content Reports only The product's category, if it's a product. One of: ANIMALS_AND_PET_SUPPLIES APPAREL_AND_ACCESSORIES ARTS_AND_ENTERTAINMENT BABY_AND_TODDLER BUSINESS_AND_INDUSTRIAL CAMERAS_AND_OPTICS ELECTRONICS FOOD_BEVERAGES_AND_TOBACCO FURNITURE HARDWARE HEALTH_AND_BEAUTY HOME_AND_GARDEN LUGGAGE_AND_BAGS MATURE MEDIA OFFICE_SUPPLIES RELIGIOUS_AND_CEREMONIAL SOFTWARE SPORTING_GOODS TOYS_AND_GAMES VEHICLES_AND_PARTS | No |
content_items[i].$product_variant | Commerce and Content Reports only The product's variant (e.g. XL, red). | No |
content_items[i].$rating_average | Commerce and Content Reports only The average rating of the item. | No |
content_items[i].$rating_count | Commerce and Content Reports only The number of ratings for the item. | No |
content_items[i].$rating_max | Commerce and Content Reports only The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating). | No |
content_items[i].$creation_timestamp | Commerce and Content Reports only The time the content was created. | No |
content_items[i].$exp_date | Commerce and Content Reports only The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set. | No |
content_items[i].$keywords | Commerce and Content Reports only keywords | No |
content_items[i].$address_street | Commerce and Content Reports only The street address for a restaurant, business, room (hotel), etc. | No |
content_items[i].$address_city | Commerce and Content Reports only The street address for a restaurant, business, room (hotel), etc. | No |
content_items[i].$address_region | Commerce and Content Reports only The state or region for a restaurant, business, room (hotel), etc. | No |
content_items[i].$address_country | Commerce and Content Reports only The country code for a restaurant, business, room (hotel), etc. | No |
content_items[i].$address_postal_code | Commerce and Content Reports only The postal/zip code for a restaurant, business, room (hotel), etc. | No |
content_items[i].$latitude | Commerce and Content Reports only The latitude for a restaurant, business, room (hotel), etc. | No |
content_items[i].$longitude | Commerce and Content Reports only The longitude for a restaurant, business, room (hotel), etc. | No |
content_items[i].$image_captions | Commerce and Content Reports only The captions associated with the image. | No |
content_items[i].$condition | Commerce and Content Reports only For auctions, whether the item is new, good, acceptable, etc. One of: OTHER NEW EXCELLENT GOOD FAIR POOR USED REFURBISHED | No |
content_items[i].$custom_fields | Commerce and Content Reports only key-value pairs that the app developer would like attached to the content item. Attached to events that are retrieved via Exports and sent via Webhooks. | No |
Required Identifiers
You must include one of the following in
user_data
:
- developer_identity
- browser_fingerprint_id
- os=iOS AND (idfa OR idfv)
- os=Android AND (android_id or aaid)
Example Requests
curl -vvv -d '{
"name": "PURCHASE",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": 25,
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip":"192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"purchase_loc": "Palo Alto",
"store_pickup": "unavailable"
},
"event_data": {
"transaction_id": "tras_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
curl -vvv -d '{
"name": "VIEW_ITEMS",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": 25,
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"purchase_loc": "Palo Alto",
"store_pickup": "unavailable"
},
"event_data": {
"search_query": "red sneakers",
"description": "Preferred purchase"
},
"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
curl -vvv -d '{
"name": "COMPLETE_REGISTRATION",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": 25,
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"foo": "bar"
},
"event_data": {
"description": "Preferred purchase"
},
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api.branch.io/v2/event/standard
Response Codes
Response Code | Definition |
---|---|
200 | Success |
Logging Custom Events
Endpoint
POST /v2/event/custom
Request Header Parameters
Parameter | Value | Required |
---|---|---|
Content-Type | application/json | Yes |
Request Body Parameters
Required Identifiers
You must include one of the following in the
user_data
:
- developer_identity
- browser_fingerprint_id
- os=iOS AND (idfa OR idfv)
- os=Android AND (android_id or aaid)
Parameter | Description | Required |
---|---|---|
branch_key | The Branch key of the originating app; from your Branch Settings Dashboard | Yes |
name | The name of the event to log. Can be a string of custom event name. For instance "picture swiped". | Yes |
user_data.os | Examples "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc. | See Required Identifiers |
user_data.os_version | The version of the operating system. | No |
user_data.environment | usually FULL_APP | No |
user_data.aaid | The Android/Google advertising ID. | See Required Identifiers |
user_data.android_id | Android hardware ID | See Required Identifiers |
user_data.idfa | iOS advertising ID | See Required Identifiers |
user_data.idfv | iOS vendor ID | See Required Identifiers |
user_data.limit_ad_tracking | true if the partner has opted to not be tracked by advertisers | No |
user_data.user_agent* | The user agent of the browser or app where the event occurred. Usually associated with a webview. | No |
user_data.browser_fingerprint_id | Branch internal-only field for tracking browsers. | See Required Identifiers |
user_data.http_origin | The current page url where Web SDK logged web session start. | No |
user_data.http_referrer | The referral url that led to the current page where Web SDK logged web session start. | No |
user_data.developer_identity | The developer-specified identity for a user. | See Required Identifiers |
user_data.country | The country code of the user, usually based on device settings or user agent string. | No |
user_data.language | The language code of the user, usually based on device settings or user agent string. | No |
user_data.ip | The ip address for the device where the event occurred | No |
user_data.local_ip | Android only : local ip of the device (e.g. "168.1.1.1") | No |
user_data.brand | The brand of the device | No |
user_data.randomized_device_token | Branch internal-only field for tracking devices. | No |
user_data.app_version | The app version downloaded by the user. | No |
user_data.model | The model of the device. | No |
user_data.screen_dpi | The screen's DPI. | No |
user_data.screen_height | The screen's height. | No |
user_data.screen_width | The screen's width. | No |
custom_data | The key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks. | No |
event_data.description | Description associated with the event. | No |
Example Request
curl -vvv -d '{
"name": "picture swiped",
"customer_event_alias": "my custom alias",
"user_data": {
"advertising_ids": {
"oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
},
"os": "Android",
"os_version": 25,
"environment": "FULL_APP",
"aaid": "abcdabcd-0123-0123-00f0-000000000000",
"android_id": "a12300000000",
"limit_ad_tracking": false,
"developer_identity": "user123",
"country": "US",
"language": "en",
"ip": "192.168.1.1",
"local_ip": "192.168.1.2",
"brand": "LGE",
"app_version": "1.0.0",
"model": "Nexus 5X",
"screen_dpi": 420,
"screen_height": 1794,
"screen_width": 1080
},
"custom_data": {
"foo": "bar"
},
"metadata": {},
"branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api.branch.io/v2/event/custom
Response Codes
Response Code | Definition |
---|---|
200 | Success |
Verify Events Sent
Once you have completed tracking events via the Events API, you can verify data is being sent to Branch for attribution. To do so, you can look at the Branch Dashboard's Liveview Records.
Wait Period
Please be patient as data may take some time to flow through Branch's attribution systems and onto the Dashboard. If data has not appeared in the Branch Dashboard after 30 minutes of completing a test event, review your API requests to see if you may have missed something.