Deep Linking API
Creating a Deep Linking URL
Endpoint - Create
POST /v1/url
Content-Type: application/json
Parameters - Create
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
data | Optional The dictionary to embed with the link. Accessed as session or install parameters from the SDK. Use the data dictionary for all link control parameters that you'll find here. |
alias | Optional Instead of our standard encoded short url, you can specify the vanity alias. For example, instead of a random string of characters/integers, you can set the vanity alias as *.app.link/devonaustin. Aliases are enforced to be unique** and immutable per domain, and per link - they cannot be reused unless deleted. Max 128 characters NOTE: If you POST to the this endpoint with the same alias, and a matching set of other POST parameters to an existing aliased link, the original will be returned to you. If it clashes and you don't specify a match, will return a HTTP 409 error. |
type | Optional
|
duration | Optional In seconds. Only set this key if you want to override the match duration for deep link matching. This is the time that Branch allows a click to remain outstanding and be eligible to be matched with a new app session. This is default set to 7200 (2 hours) |
Branch analytics parameters | Optional It's important to tag your links with an organized structure of analytics labels so that the data appears consistent and readable in the dashboard. |
identity | Optional The identity used to identify the user. If the link is not tied to an identity, there's no need to specify an identity. Max 127 characters |
Sample Request - Create
curl -XPOST https://api2.branch.io/v1/url -H "Content-Type: application/json" \
-d '{
"branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
"channel": "facebook",
"feature": "onboarding",
"campaign": "new product",
"stage": "new user",
"tags": ["one", "two", "three"],
"data": {
"$canonical_identifier": "content/123",
"$og_title": "Title from Deep Link",
"$og_description": "Description from Deep Link",
"$og_image_url": "http://www.lorempixel.com/400/400/",
"$desktop_url": "http://www.example.com",
"custom_boolean": true,
"custom_integer": 1243,
"custom_string": "everything",
"custom_array": [1,2,3,4,5,6],
"custom_object": { "random": "dictionary" }
}
}'
Sample Response - Create
{
"url": "https://example.app.link/WgiqvsepqF"
}
Bulk creating Deep Linking URLs
For more details on how to create links, see the Branch link creation guide
Endpoint - Bulk Create
POST /v1/url/bulk/:branch_key
Content-Type: application/json
Parameters - Bulk Create
A json array of parameters from Creating a Deep Linking URL.
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
Branch Parameters | Optional You're free to add any of your own key-value parameters to a Branch link. These parameters will be passed to your app via the Branch SDK |
Note: there is a 100KB limit on the request payload size
Sample Request - Bulk Create
curl -XPOST https://api2.branch.io/v1/url/bulk/key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt -H "Content-Type: application/json" \
-d '[
{
"channel": "facebook",
"feature": "onboarding",
"campaign": "new product",
"stage": "new user",
"tags": ["one", "two", "three"],
"data": {
"$canonical_identifier": "content/123",
"$og_title": "Title from Deep Link",
"$og_description": "Description from Deep Link",
"$og_image_url": "http://www.lorempixel.com/400/400/",
"$desktop_url": "http://www.example.com",
"custom_boolean": true,
"custom_integer": 1243,
"custom_string": "everything",
"custom_array": [1,2,3,4,5,6],
"custom_object": { "random": "dictionary" }
}
},
{
"channel": "facebook",
"feature": "onboarding",
"campaign": "new product",
"stage": "new user",
"tags": ["one", "two", "three"],
"data": {
"$canonical_identifier": "content/123",
"$og_title": "Title from Deep Link",
"$og_description": "Description from Deep Link",
"$og_image_url": "http://www.lorempixel.com/400/400/",
"$desktop_url": "http://www.example.com"
}
}
]'
Sample Response - Bulk Create
An array of deep linking urls and/or errors in case invalid params.
[
{
"url": "https://example.app.link/0AjuiLcpqF"
},
{
"url": "https://example.app.link/5IULiLcpqF"
},
{
'error': 'error message'
}
]
Deleting Existing Links
Not Available in Testing Environment
Endpoint - Delete
DELETE /v1/url
Content-Type: application/json
Parameters - Delete
Parameters |
---|
[access_key | REQUIRED Your API Key / Access Token; Learn how to retrieve your API key (a.k.a. Access Token) |
Sample Request - Delete
curl -X DELETE \
'https://api2.branch.io/v1/url?url=https://example.app.link/ABCD&app_id=YOUR_APP_ID' \
-H "Access-Token: YOUR_ACCESS_TOKEN"
Sample Response - Delete
{
"url": "https://example.app.link/ABCD",
"deleted": true
}
Reading Existing Deep Links
Returns deep link properties.
Endpoint - Read
GET /v1/url
Content-Type: application/json
Parameters - Read
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
url | REQUIRED The deep link url you want read. |
Sample Request - Read
curl -XGET 'https://api2.branch.io/v1/url?url=https://example.app.link/WgiqvsepqF&branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt'
Sample Response - Read
{
"campaign": "new product",
"channel": "facebook",
"feature": "onboarding",
"stage": "new user",
"tags": [
"one",
"two",
"three"
],
"data": {
"$canonical_identifier": "content/123",
"$desktop_url": "http://www.example.com",
"$og_description": "Description from Deep Link",
"$og_image_url": "http://www.lorempixel.com/400/400/",
"$og_title": "Title from Deep Link",
"$one_time_use": false,
"custom_array": [
1,
2,
3,
4,
5,
6
],
"custom_boolean": true,
"custom_integer": 1243,
"custom_object": {
"random": "dictionary"
},
"custom_string": "everything",
"~campaign": "new product",
"~channel": "facebook",
"~creation_source": 0,
"~feature": "onboarding",
"~id": "423196192848102356",
"~stage": "new user",
"~tags": [
"one",
"two",
"three"
],
"url": "https://example.app.link/WgiqvsepqF"
},
"type": 0,
"alias": null
}
Updating Existing Deep Links
Endpoint - Update
PUT /v1/url
Content-Type: application/json
Parameters - Update
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
branch_secret | REQUIRED The Branch secret if the originating app; from your Branch Settings Dashboard |
url | REQUIRED The deep link url you want updated. |
Sample Request - Update
curl -XPUT 'https://api2.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2F5IULiLcpqF' -H "Content-Type: application/json" \
-d '{
"branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
"branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
"channel": "twitter",
"data":{
"name":"alex",
"user_id":"12346"
}
}'
Sample Response - Update
{
"campaign": "new product",
"channel": "twitter",
"feature": "onboarding",
"stage": "new user",
"tags": [
"one",
"two",
"three"
],
"data": {
"$one_time_use": false,
"name": "alex",
"user_id": "12346",
"~campaign": "new product",
"~channel": "twitter",
"~creation_source": 0,
"~feature": "onboarding",
"~id": "423196096467215333",
"~stage": "new user",
"~tags": [
"one",
"two",
"three"
],
"url": "https://example.app.link/5IULiLcpqF"
},
"type": 0,
"alias": null
}
Link Update Tips
A link's data object is overwritten entirely by the Link update API, so make sure to include all of the link's data when updating it (not just the data you're changing)
To update links in bulk, combine the Link update and Link read APIs when creating a script. The sample Python script below reads a 2-column CSV file, and updates a key specified in the script for all links listed in column A, with the values in column B:
import requests
import csv
import sys
import urllib
import json
def BranchUpdateModule(KeyV, SecretV, UpdateV, File):
#Insert API key & App Secret from the Branch dashboard, and the Link data key you want to change in each link **
branch_key = KeyV
branch_secret = SecretV
key_to_update = UpdateV
#Insert filename for CSV containing links to update in first column, and values to add in second column **
ifile = open(File, "r", encoding="utf-8")
#Constants
branchendpoint = "https://api2.branch.io/v1/url?url="
reader = csv.reader(ifile, delimiter=',')
# Uncomment the next line if you want the script to skip the first line of the CSV
next(reader)
# Loop through CSV
for row in reader:
# Retrieve link data for link being updated
url = urllib.parse.quote_plus(row[0])
getrequest = branchendpoint + url + "&branch_key=" + branch_key
linkdata = requests.get(getrequest)
jsonData = json.loads(linkdata.text)
if linkdata.status_code != 200:
print('Failed: {}'.format( getrequest))
continue
# Set credentials for update API
jsonData["branch_key"] = branch_key
jsonData["branch_secret"] = branch_secret
#TODO for editing new value
newValue = row[1]
if key_to_update in jsonData:
jsonData[key_to_update] = newValue
if key_to_update in jsonData["data"]:
jsonData["data"][key_to_update] = newValue
if jsonData.get('type', None) is not None:
del jsonData['type']
if jsonData.get('alias', None):
del jsonData['alias']
payload = json.dumps(jsonData)
#print("\n \n payload")
#print(payload)
putrequest = branchendpoint + url
print(putrequest)
r = requests.put(putrequest, json=jsonData)
#print("\n \n")
print(r.url)
print(r)
# print
ifile.close()
Restrictions
There are certain restrictions when attempting to update links:
- Not all links are updateable, namely links with the structure of
bnc.lt/c/
orbnc.lt/d/
- The alias of a link cannot be updated, e.g. 'https://bnc.lt/test' -> 'https://bnc.lt/test1'
- The identity associated with a Branch link cannot be updated
- The
type
of a link cannot be changed, e.g. a marketing link is type 2, and a standard link generated by our Branch SDK is type 0 - The following additional fields cannot be updated:
app_id
randomized_bundle_token
domain
state
creation_source
app_short_identifier
Logging Commerce Events
Endpoint - Commerce
POST /v2/event/standard
Content-Type: application/json
Parameters - Commerce
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
name | REQUIRED The name of the event to log. Can be one of the following: ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS |
customer_event_alias | Optional The event alias as defined by you; used in addition to the event name defined above. |
user_data.os | REQUIRED Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc. |
user_data.os_version | Optional The version of the operating system. |
user_data.environment | Optional usually FULL_APP |
user_data.aaid | Optional The Android/Google advertising ID. |
user_data.android_id | Optional Android hardware ID |
user_data.idfa | Optional iOS advertising ID |
user_data.idfv | Optional iOS vendor ID |
user_data.limit_ad_tracking | Optional true if the partner has opted to not be tracked by advertisers |
user_data.user_agent | Optional The user agent of the browser or app where the event occurred. Usually associated with a webview. |
user_data.browser_fingerprint_id | Optional Branch internal-only field for tracking browsers. |
user_data.http_origin | Optional The current page url where Web SDK logged web session start. |
user_data.http_referrer | Optional The referral url that led to the current page where Web SDK logged web session start. |
user_data.developer_identity | Optional The developer-specified identity for a user. |
user_data.country | Optional The country code of the user, usually based on device settings or user agent string. |
user_data.language | Optional The language code of the user, usually based on device settings or user agent string. |
user_data.ip | REQUIRED The ip address for the device where the event occurred |
user_data.local_ip | Optional Android only : local ip of the device (e.g. "168.1.1.1") |
user_data.brand | Optional The brand of the device |
user_data.randomized_device_token | Optional Branch internal-only field for tracking devices. |
user_data.app_version | Optional The app version downloaded by the user. |
user_data.model | Optional The model of the device. |
user_data.screen_dpi | Optional The screen's DPI. |
user_data.screen_heighti | Optional The screen's height. |
user_data.screen_width | Optional The screen's width. |
custom_data | Optional 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. |
event_data.transaction_id | Optional The partner-specified transaction id for their internal use |
event_data.revenue | Optional The partner-specified reported revenue for the event. |
event_data.currency | Optional Currency that revenue, price, shipping, tax were originally reported in by the partner |
event_data.shipping | Optional Shipping cost associated with the transaction. |
event_data.tax | Optional Total tax associated with the transaction. |
event_data.coupon | Optional Transaction coupon redeemed with the transaction (e.g. "SPRING2017") |
event_data.affiliation | Optional Store or affiliation from which this transaction occurred (e.g. Google Store) |
event_data.description | Optional Description associated with the event, not necessarily specific to any individual content items (see below) |
content_items[i].$content_schema | Optional category / schema for a piece of content. May be used in the future for analytics. One of: |
content_items[i].$og_title | Optional The title (for the individual content item). |
content_items[i].$og_image_url | Optional The image URL (for the individual content item). |
content_items[i].$canonical_identifier | Optional used to allow Branch to unify content/messages for Content Analytics |
content_items[i].$publicly_indexable | Optional true |
content_items[i].$locally_indexable | Optional
|
content_items[i].$price | Optional The price for the product/content. |
content_items[i].$quantity | Optional The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc). |
content_items[i].$sku | Optional The product sku or product ID. |
content_items[i].$product_name | Optional The product's name. |
content_items[i].$product_brand | Optional The product's brand. |
content_items[i].$product_category | Optional The product's category, if it's a product. One of: |
content_items[i].$product_variant | Optional The product's variant (e.g. XL, red). |
content_items[i].$rating_average | Optional The average rating of the item. |
content_items[i].$rating_count | Optional The number of ratings for the item. |
content_items[i].$rating_max | Optional The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating). |
content_items[i].$creation_timestamp | Optional The time the content was created. |
content_items[i].$exp_date | Optional The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set. |
content_items[i].$keywords | Optional keywords |
content_items[i].$address_street | Optional The street address for a restaurant, business, room (hotel), etc. |
content_items[i].$address_city | Optional The street address for a restaurant, business, room (hotel), etc. |
content_items[i].$address_region | Optional The state or region for a restaurant, business, room (hotel), etc. |
content_items[i].$address_country | Optional The country code for a restaurant, business, room (hotel), etc. |
content_items[i].$address_postal_code | Optional The postal/zip code for a restaurant, business, room (hotel), etc. |
content_items[i].$latitude | Optional The latitude for a restaurant, business, room (hotel), etc. |
content_items[i].$longitude | Optional The longitude for a restaurant, business, room (hotel), etc. |
content_items[i].$image_captions | Optional The captions associated with the image. |
content_items[i].$condition | Optional For auctions, whether the item is new, good, acceptable, etc. One of: |
content_items[i].$custom_fields | Optional 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 |
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)
Sample Request - Commerce
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
Sample Response - Commerce
{ "branch_view_enabled": true/false }
Logging Content Events
Endpoint - Content
POST /v2/event/standard
Content-Type: application/json
Parameters - Content
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
name | REQUIRED The name of the event to log. Can be one of the following: SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE |
customer_event_alias | Optional The event alias as defined by you; used in addition to the event name defined above |
user_data.os | REQUIRED Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc. |
user_data.os_version | Optional The version of the operating system. |
user_data.environment | Optional usually FULL_APP |
user_data.aaid | Optional The Android/Google advertising ID. |
user_data.android_id | Optional Android hardware ID |
user_data.idfad | Optional iOS advertising ID |
user_data.idfv | Optional iOS vendor ID |
user_data.limit_ad_tracking | Optional true if the partner has opted to not be tracked by advertisers |
user_data.user_agent | Optional The user agent of the browser or app where the event occurred. Usually associated with a webview. |
user_data.browser_fingerprint_id | Optional Branch internal-only field for tracking browsers. |
user_data.http_origin | Optional The current page url where Web SDK logged web session start. |
user_data.http_referrer | Optional The referral url that led to the current page where Web SDK logged web session start. |
user_data.developer_identity | Optional The developer-specified identity for a user. |
user_data.country | Optional The country code of the user, usually based on device settings or user agent string. |
user_data.language | Optional The language code of the user, usually based on device settings or user agent string. |
user_data.ip | YES The ip address for the device where the event occurred |
user_data.local_ip | Optional Android only : local ip of the device (e.g. "168.1.1.1") |
user_data.brand | Optional The brand of the device |
user_data.randomized_device_token | Optional Branch internal-only field for tracking devices. |
user_data.app_version | Optional The app version downloaded by the user. |
user_data.model | Optional The model of the device. |
user_data.screen_dpi | Optional The screen's DPI. |
user_data.screen_height | Optional The screen's height. |
user_data.screen_width | Optional The screen's width. |
custom_data | Optional 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. |
event_data.transaction_id | Optional The partner-specified transaction id for their internal use |
event_data.revenue | Optional The partner-specified reported revenue for the event. |
event_data.currency | Optional Currency that revenue, price, shipping, tax were originally reported in by the partner |
event_data.shipping | Optional Shipping cost associated with the transaction. |
event_data.tax | Optional Total tax associated with the transaction. |
event_data.coupon | Optional Transaction coupon redeemed with the transaction (e.g. "SPRING2017") |
event_data.affiliation | Optional Store or affiliation from which this transaction occurred (e.g. Google Store) |
event_data.description | Optional Description associated with the event, not necessarily specific to any individual content items (see below) |
content_items[i].$content_schema | Optional category / schema for a piece of content. May be used in the future for analytics. One of: |
content_items[i].$og_title | Optional The title (for the individual content item). |
content_items[i].$og_description | Optional The description (for individual content item). |
content_items[i].$og_image_url | Optional The image URL (for the individual content item). |
content_items[i].$canonical_identifier | Optional used to allow Branch to unify content/messages for Content Analytics |
content_items[i].$publicly_indexable | Optional
|
content_items[i].$locally_indexable | Optional
|
content_items[i].$price | Optional The price for the product/content. |
content_items[i].$quantity | Optional The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc). |
content_items[i].$sku | Optional The product sku or product ID. |
content_items[i].$product_name | Optional The product's name. |
content_items[i].$product_brand | Optional The product's brand. |
ccontent_items[i].$product_category | Optional The product's category, if it's a product. One of: |
content_items[i].$product_variant | Optional The product's variant (e.g. XL, red). |
content_items[i].$rating_average | Optional The average rating of the item. |
content_items[i].$rating_count | Optional The number of ratings for the item. |
content_items[i].$rating_max | Optional The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating). |
content_items[i].$creation_timestamp | Optional The time the content was created. |
content_items[i].$exp_date | Optional The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set. |
content_items[i].$keywords | Optional keywords |
content_items[i].$address_street | Optional The street address for a restaurant, business, room (hotel), etc. |
content_items[i].$address_city | Optional The street address for a restaurant, business, room (hotel), etc. |
content_items[i].$address_region | Optional The state or region for a restaurant, business, room (hotel), etc. |
content_items[i].$address_country | Optional The country code for a restaurant, business, room (hotel), etc. |
content_items[i].$address_postal_code | Optional The postal/zip code for a restaurant, business, room (hotel), etc. |
content_items[i].$latitude | Optional The latitude for a restaurant, business, room (hotel), etc. |
content_items[i].$longitude | Optional The longitude for a restaurant, business, room (hotel), etc. |
content_items[i].$image_captions | Optional The captions associated with the image. |
content_items[i].$condition | Optional For auctions, whether the item is new, good, acceptable, etc. One of: |
content_items[i].$custom_fields | Optional 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. |
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)
Sample Request - Content
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
Sample Response - Content
{ "branch_view_enabled": true/false }
Logging User Lifecycle Events
Endpoint - Lifecycle
POST /v2/event/standard
Content-Type: application/json
Parameters - Lifecycle
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
name | REQUIRED The name of the event to log. Can be one of the following: ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS |
user_data.os | REQUIRED Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc. |
user_data.os_version | Optional The version of the operating system. |
user_data.environment | Optional usually FULL_APP |
user_data.aaid | Optional The Android/Google advertising ID. |
user_data.android_id | Optional Android hardware ID |
user_data.idfa | Optional iOS advertising ID |
user_data.idfv | Optional iOS vendor ID |
user_data.limit_ad_tracking | Optional true if the partner has opted to not be tracked by advertisers |
user_data.user_agent | Optional The user agent of the browser or app where the event occurred. Usually associated with a webview. |
user_data.browser_fingerprint_id | Optional Branch internal-only field for tracking browsers. |
user_data.http_origin | Optional The current page url where Web SDK logged web session start. |
user_data.http_referrer | Optional The referral url that led to the current page where Web SDK logged web session start. |
user_data.developer_identity | Optional The developer-specified identity for a user. |
user_data.country | Optional The country code of the user, usually based on device settings or user agent string. |
user_data.language | Optional The language code of the user, usually based on device settings or user agent string. |
user_data.ip | REQUIRED The ip address for the device where the event occurred |
user_data.local_ip | Optional Android only : local ip of the device (e.g. "168.1.1.1") |
user_data.brand | Optional The brand of the device |
user_data.randomized_device_token | Optional Branch internal-only field for tracking devices. |
user_data.app_version | Optional The app version downloaded by the user. |
user_data.model | Optional The model of the device. |
user_data.screen_dpi | Optional The screen's DPI. |
user_data.screen_height | Optional The screen's height. |
user_data.screen_width | Optional The screen's width. |
custom_data | Optional 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. |
event_data.description | Optional Description associated with the event. |
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)
Sample Request - Lifecycle
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
Sample Response - Lifecycle
{ "branch_view_enabled": true/false }
Logging Custom Events
Endpoint - Custom
POST /v2/event/custom
Content-Type: application/json
Parameters - Custom
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
name | REQUIRED The name of the event to log. Can be a string of custom event name. For instance "picture swiped". |
user_data.os | REQUIRED Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc. |
user_data.os_version | Optional The version of the operating system. |
user_data.environment | Optional usually FULL_APP |
user_data.aaid | Optional The Android/Google advertising ID. |
user_data.android_id | Optional Android hardware ID |
user_data.idfa | Optional iOS advertising ID |
user_data.idfv | Optional iOS vendor ID |
user_data.limit_ad_tracking | Optional true if the partner has opted to not be tracked by advertisers |
user_data.user_agent | Optional The user agent of the browser or app where the event occurred. Usually associated with a webview. |
user_data.browser_fingerprint_id | Optional Branch internal-only field for tracking browsers. |
user_data.http_origin | Optional The current page url where Web SDK logged web session start. |
user_data.http_referrer | Optional The referral url that led to the current page where Web SDK logged web session start. |
user_data.developer_identity | Optional The developer-specified identity for a user. |
user_data.country | Optional The country code of the user, usually based on device settings or user agent string. |
user_data.language | Optional The language code of the user, usually based on device settings or user agent string. |
user_data.ip | REQUIRED The ip address for the device where the event occurred |
user_data.local_ip | Optional Android only : local ip of the device (e.g. "168.1.1.1") |
user_data.brand | Optional The brand of the device |
user_data.randomized_device_token | Optional Branch internal-only field for tracking devices. |
user_data.app_version | Optional The app version downloaded by the user. |
user_data.model | Optional The model of the device. |
user_data.screen_dpi | Optional The screen's DPI. |
user_data.screen_height | Optional The screen's height. |
user_data.screen_width | Optional The screen's width. |
custom_data | Optional 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. |
event_data.description | ** Description associated with the event. |
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)
Sample Request - Custom
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
Sample Response - Custom
{ }
Getting Current Branch App Config
Endpoint - Get App Config
GET /v1/app/[branch key]?branch_secret=[branch secret]
Parameters - Get App Config
Parameters |
---|
branch_key | REQUIRED The Branch key of the originating app; from your Branch Settings Dashboard |
branch_secret | REQUIRED The Branch secret if the originating app; from your Branch Settings Dashboard |
Returns - Get App Config
{
branch_key: "the app key",
branch_secret: "the app secret",
creation_date : "date app was created",
app_name: "name of the app",
dev_name: "main contact name",
dev_email: "main contact email",
dev_phone_number: "main contact phone",
android_app: "whether an Android app is enabled",
android_url: "url of Android store, or namespace (com.android.myapp)",
android_uri_scheme: "the Android URI scheme",
android_package_name: "the Android package name",
sha256_cert_fingerprints: "the SHA256 fingerprints for App Links",
android_app_links_enabled: "whether App Links are enabled",
ios_app: "whether an iOS app is enabled",
ios_url: "url of iOS store, or app id (id512451233)",
ios_uri_scheme: "the iOS URI scheme",
ios_store_country: "the country code of the app, default to US",
ios_bundle_id: "the iOS bundle ID",
ios_team_id: "the iOS Team ID",
universal_linking_enabled: "whether Universal Links are enabled",
fire_url: "the redirect on Fire phones",
windows_phone_url: "the redirect on Windows phones",
blackberry_url: "The redirect on Blackberry phones",
web_url: "backup website if URLs are null",
default_desktop_url: "the default desktop redirect, or null if set to hosted SMS",
short_url_domain: "white labeled domain for short links",
text_message: "text message to use, {{ link }} will be replaced with short link",
og_app_id: "optional default Open Graph (OG) app id",
og_title: "optional default OG title",
og_image_url: "optional default OG image URL",
og_description: "optional default OG description",
deepview_desktop: "the current deepview selected for the desktop platform",
deepview_ios: "the current deepview selected for the iOS platform",
deepview_android: "the current deepview selected for the Android platform",
}
Updating a Branch App Config
Endpoint - Update App Config
PUT /v1/app/:branch_key
Content-Type: application/json
Parameters - Update App Config
Parameters |
---|
branch_secret | REQUIRED The Branch secret if the originating app; from your Branch Settings Dashboard |
app_name | Optional The name of the app (max 255 characters). |
dev_name | Optional The main contact developer name (max 255 characters). |
dev_email | Optional The main contact developer email (max 255 characters). |
android_url | Optional The url of the Android store, or package name (com.android.myapp). Note that to set a fallback URL for Android instead, you must also set |
android_uri_scheme | Optional The Android URI scheme. |
ios_url | Optional The url of iOS store, or app id (id512451233) |
ios_uri_scheme | Optional The iOS URI scheme. |
ios_store_country | Optional The country code of the app, default to US (max 255 characters). |
web_url | Optional Backup website if URLs are null. |
text_message | Optional The text message to use for text-me feature, {{ link }} will be replaced with short link (max 255 characters). |
og_app_id | Optional Default Open Graph (OG) app id (max 255 characters). |
og_title | Optional Default OG title to be used with links (max 255 characters). |
og_description | Optional Default OG description to be used with links (max 255 characters). |
og_image_url | Optional Default OG image URL to be used with links (max 255 characters). |
Returns - Update App Config
{
branch_key: "the app key",
branch_secret: "the app secret",
creation_date : "date app was created",
app_name: "name of the app",
dev_name: "main contact name",
dev_email: "main contact email",
dev_phone_number: "main contact phone",
android_url: "url of Android store, or namespace (com.android.myapp)",
android_uri_scheme: "the Android URI scheme",
ios_url: "url of iOS store, or app id (id512451233)",
ios_uri_scheme: "the iOS URI scheme",
ios_store_country: "the country code of the app, default to US",
web_url: "backup website if URLs are null",
short_url_domain: "white labeled domain for short links",
text_message: "text message to use, {{ link }} will be replaced with short link",
og_app_id: "optional default Open Graph (OG) app id",
og_title: "optional default OG title",
og_image_url: "optional default OG image URL",
og_description: "optional default OG description"
}
Updated about 1 month ago