👍

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:

  1. 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.

12701270

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
对于拍卖,该物品是否是新的,良好的,可以接受的,等等

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

  1. developer_identity
  2. browser_fingerprint_id
  3. os = iOS AND(idfa OR idfv)
  4. 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

  1. developer_identity
  2. browser_fingerprint_id
  3. os = iOS AND(idfa OR idfv)
  4. 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.

16721672

📘

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.