Events API

👍
Try It!
Try out the Events API for your Branch App via the API reference here.

概述

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.

先决条件

In order to access the Events API, you need to have completed the following:

Created a Branch Dashboard

认证

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

参数	值	必要项
Content-Type	application/json	是

Request Body Parameters

参数	描述	必要项
branch_key	The Branch key of the originating app; from your Branch Settings Dashboard	是
名称	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	是
customer_event_alias	您定义的事件 alias；在以上定义的事件名称外使用。	否
user_data.os	Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc.	是
user_data.os_version	The version of the operating system.	否
user_data.environment	usually FULL_APP	否
user_data.aaid	Android/Google 广告 ID。	否
user_data.android_id	Android 硬件 ID	否
user_data.idfa	iOS 广告 ID	否
user_data.idfv	iOS 供应商 ID	否
user_data.limit_ad_tracking	true if the partner has opted to not be tracked by advertisers	否
user_data.user_agent	发生事件的浏览器或应用的用户代理。通常与 webview 关联。	否
user_data.browser_fingerprint_id	Branch 内部专用字段，用于追踪浏览器。	否
user_data.http_origin	Web SDK 记录的 Web 会话开始的当前页面 URL。	否
user_data.http_referrer	referral url 指向 Web SDK 记录 Web 会话开始的当前页面。	否
user_data.developer_identity	开发者为用户指定的身份。	否
user_data.country	用户的国家/地区代码，通常基于设备设置或用户代理 String。	否
user_data.language	用户的语言代码，通常基于设备设置或用户代理 string。	否
user_data.ip	事件发生的设备 IP 地址	是
user_data.local_ip	Android only : local ip of the device (e.g. "168.1.1.1")	否
user_data.brand	设备的品牌	否
user_data.randomized_device_token	Branch 内部专用字段，用于追踪设备。	否
user_data.app_version	用户下载的应用版本。	否
user_data.model	设备的型号。	否
user_data.screen_dpi	屏幕的 DPI。	否
user_data.screen_height	屏幕的高度。	否
user_data.screen_width	屏幕的宽度。	否
custom_data	应用开发人员想要附加到事件的 key-values pairs。附加到通过导出获得并通过 Webhooks 发送的事件。	否
event_data.transaction_id	合作伙伴指定的内部使用交易 (transaction) ID	否
event_data.revenue	合作伙伴指定的事件报告收入。	否
event_data.currency	合作伙伴最初报告收入，价格，运费，税金的货币	否
event_data.shipping	与交易相关的运输 cost。	否
event_data.tax	与交易相关的总税额。	否
event_data.coupon	随交易兑换的交易优惠券（例如 “SPRING2017”）	否
event_data.affiliation	发生此交易的商店或联盟关系（例如 Google Store）	否
event_data.description	与事件相关的描述，不一定特定于任何单个内容项（请参见下文）	否
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	否
content_items[i].$og_title	*Commerce and Content Reports only* 标题（用于单个内容项）。	否
content_items[i].$og_image_url	*Commerce and Content Reports only* 图片 URL（用于单个内容项）。	否
content_items[i].$canonical_identifier	*Commerce and Content Reports only* Used to allow Branch to unify content/messages for Content Analytics	否
content_items[i].$publicly_indexable	*Commerce and Content Reports only* `true`: content can be seen by anyone `false`: cannot index for public use	否
content_items[i].$locally_indexable	*Commerce and Content Reports only* `true`: content can be indexed for local (device) use `false`: cannot index for local use	否
content_items[i].$price	*Commerce and Content Reports only* 产品/内容的价格。	否
content_items[i].$quantity	*Commerce and Content Reports only* The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc).	否
content_items[i].$sku	*Commerce and Content Reports only* 产品 sku 或产品 ID。	否
content_items[i].$product_name	*Commerce and Content Reports only* 产品名称。	否
content_items[i].$product_brand	*Commerce and Content Reports only* 产品的品牌。	否
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	否
content_items[i].$product_variant	*Commerce and Content Reports only* 产品的型号（例如 XL，红色）。	否
content_items[i].$rating_average	*Commerce and Content Reports only* 该项目的平均评分。	否
content_items[i].$rating_count	*Commerce and Content Reports only* 该项目的评分数。	否
content_items[i].$rating_max	*Commerce and Content Reports only* 该项目的最高可能评分（例如，如果5星最高，则为5.0）。	否
content_items[i].$creation_timestamp	*Commerce and Content Reports only* 内容创建的时间。	否
content_items[i].$exp_date	*Commerce and Content Reports only* 最后一次之后，此内容将不再有效。 null / 0表示没有限制。不建议经常设置。	否
content_items[i].$keywords	*Commerce and Content Reports only* 关键字	否
content_items[i].$address_street	*Commerce and Content Reports only* 餐厅，公司，房间（酒店）等的街道地址。	否
content_items[i].$address_city	*Commerce and Content Reports only* 餐厅，公司，房间（酒店）等的街道地址。	否
content_items[i].$address_region	*Commerce and Content Reports only* 餐馆，公司，房间（酒店）等的州或地区	否
content_items[i].$address_country	*Commerce and Content Reports only* 餐厅，公司，房间（酒店）等的国家/地区代码	否
content_items[i].$address_postal_code	*Commerce and Content Reports only* 餐厅，公司，房间（酒店）等的邮政编码	否
content_items[i].$latitude	*Commerce and Content Reports only* 餐厅，公司，房间（酒店）等的纬度	否
content_items[i].$longitude	*Commerce and Content Reports only* 餐馆，公司，房间（酒店）等的经度	否
content_items[i].$image_captions	*Commerce and Content Reports only* 与图像关联的标题	否
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	否
content_items[i].$custom_fields	*Commerce and Content Reports only* 应用开发人员想要附加到内容项的 key-values pairs。附加到通过导出获得并通过 Webhooks 发送的事件。	否

❗️
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)

示例请求

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	定义
200	成功

记录自定义事件

Endpoint

POST /v2/event/custom

Request Header Parameters

参数	值	必要项
Content-Type	application/json	是

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)

参数	描述	必要项
branch_key	The Branch key of the originating app; from your Branch Settings Dashboard	是
名称	要记录的事件的名称。可以是自定义事件名称的 string。例如 “滑动图片”。	是
user_data.os	Examples "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc.	See Required Identifiers
user_data.os_version	The version of the operating system.	否
user_data.environment	usually FULL_APP	否
user_data.aaid	Android/Google 广告 ID。	See Required Identifiers
user_data.android_id	Android 硬件 ID	See Required Identifiers
user_data.idfa	iOS 广告 ID	See Required Identifiers
user_data.idfv	iOS 供应商 ID	See Required Identifiers
user_data.limit_ad_tracking	`true` if the partner has opted to not be tracked by advertisers	否
user_data.user_agent*	发生事件的浏览器或应用的用户代理。通常与 webview 关联。	否
user_data.browser_fingerprint_id	Branch 内部专用字段，用于追踪浏览器。	See Required Identifiers
user_data.http_origin	Web SDK 记录的 Web 会话开始的当前页面 URL。	否
user_data.http_referrer	referral url 指向 Web SDK 记录 Web 会话开始的当前页面。	否
user_data.developer_identity	开发者为用户指定的身份。	See Required Identifiers
user_data.country	用户的国家/地区代码，通常基于设备设置或用户代理 String。	否
user_data.language	用户的语言代码，通常基于设备设置或用户代理 string。	否
user_data.ip	事件发生的设备 IP 地址	否
user_data.local_ip	Android only : local ip of the device (e.g. "168.1.1.1")	否
user_data.brand	设备的品牌	否
user_data.randomized_device_token	Branch 内部专用字段，用于追踪设备。	否
user_data.app_version	用户下载的应用版本。	否
user_data.model	设备的型号。	否
user_data.screen_dpi	屏幕的 DPI。	否
user_data.screen_height	屏幕的高度。	否
user_data.screen_width	屏幕的宽度。	否
custom_data	应用开发人员想要附加到事件的 key-values pairs。附加到通过导出获得并通过 Webhooks 发送的事件。	否
event_data.description	与事件关联的描述。	否

请求示例

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	定义
200	成功

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.

Events API

👍
Try It!

概述

先决条件

认证

API Usage

Logging Standard Events - Commerce, Content, User Lifecycle

Endpoint

Request Header Parameters

Request Body Parameters

❗️
Required Identifiers

示例请求

Response Codes

记录自定义事件

Endpoint

Request Header Parameters

Request Body Parameters

❗️
Required Identifiers

请求示例

Response Codes

Verify Events Sent

📘
Wait Period

筛选项

👍Try It!

概述

先决条件

认证

API Usage

Logging Standard Events - Commerce, Content, User Lifecycle

Endpoint

Request Header Parameters

Request Body Parameters

❗️Required Identifiers

示例请求

Response Codes

记录自定义事件

Endpoint

Request Header Parameters

Request Body Parameters

❗️Required Identifiers

请求示例

Response Codes

Verify Events Sent

📘Wait Period

👍
Try It!

❗️
Required Identifiers

❗️
Required Identifiers

📘
Wait Period