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: Content: User Lifecycle: | 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 | No |
content_items[i].$og_title | Commerce and Content Reports only | No |
content_items[i].$og_image_url | Commerce and Content Reports only | No |
content_items[i].$canonical_identifier | Commerce and Content Reports only | No |
content_items[i].$publicly_indexable | Commerce and Content Reports only | No |
content_items[i].$locally_indexable | Commerce and Content Reports only | No |
content_items[i].$price | Commerce and Content Reports only | No |
content_items[i].$quantity | Commerce and Content Reports only | No |
content_items[i].$sku | Commerce and Content Reports only | No |
content_items[i].$product_name | Commerce and Content Reports only | No |
content_items[i].$product_brand | Commerce and Content Reports only | No |
content_items[i].$product_category | Commerce and Content Reports only | No |
content_items[i].$product_variant | Commerce and Content Reports only | No |
content_items[i].$rating_average | Commerce and Content Reports only | No |
content_items[i].$rating_count | Commerce and Content Reports only | No |
content_items[i].$rating_max | Commerce and Content Reports only | No |
content_items[i].$creation_timestamp | Commerce and Content Reports only | No |
content_items[i].$exp_date | Commerce and Content Reports only | No |
content_items[i].$keywords | Commerce and Content Reports only | No |
content_items[i].$address_street | Commerce and Content Reports only | No |
content_items[i].$address_city | Commerce and Content Reports only | No |
content_items[i].$address_region | Commerce and Content Reports only | No |
content_items[i].$address_country | Commerce and Content Reports only | No |
content_items[i].$address_postal_code | Commerce and Content Reports only | No |
content_items[i].$latitude | Commerce and Content Reports only | No |
content_items[i].$longitude | Commerce and Content Reports only | No |
content_items[i].$image_captions | Commerce and Content Reports only | No |
content_items[i].$condition | Commerce and Content Reports only One of: | No |
content_items[i].$custom_fields | Commerce and Content Reports only | 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 |
| 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.