Events API

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

전제 조건

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

엔드 포인트

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	예
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	예
customer_event_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	안드로이드 / 구글 광고 ID입니다.	아니오
user_data.android_id	안드로이드 하드웨어 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	이벤트가 발생한 브라우저 또는 앱의 유저 에이전트입니다. 일반적으로 웹 뷰와 연결됩니다.	아니오
user_data.browser_fingerprint_id	브라우저 트래킹을 위한 Branch 내부 전용 필드입니다.	아니오
user_data.http_origin	Web SDK가 웹 세션 시작을 로그한 현재 페이지 URL입니다.	아니오
user_data.http_referrer	Web SDK가 웹 세션 시작을 로그한 현재 페이지로 연결되는 참조 URL입니다.	아니오
user_data.developer_identity	유저의 개발자 지정 ID입니다.	아니오
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입니다. Export를 통해 검색되고 Webhook을 통해 전송되는 이벤트에 첨부됩니다.	아니오
event_data.transaction_id	내부 사용을 위한 파트너 지정 트랜잭션 ID	아니오
event_data.revenue	이벤트에 대해 파트너가 지정한 리포트 수익입니다.	아니오
event_data.currency	파트너가 수익, 가격, 배송, 세금을 처음 리포트한 통화	아니오
event_data.shipping	트랜잭션과 관련된 배송비입니다.	아니오
event_data.tax	트랜잭션과 관련된 총 세금입니다.	아니오
event_data.coupon	트랜잭션 시 교환한 트랜잭션 쿠폰 (예: "SPRING2017")	아니오
event_data.affiliation	해당 트랜잭션이 발생한 상점 또는 가맹 (예: 구글 스토어)	아니오
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입니다. Export를 통해 검색되고 Webhook을 통해 전송되는 이벤트에 첨부됩니다.	아니오

❗️
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	성공

커스텀 이벤트 로깅

엔드 포인트

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	예
name	로그 할 이벤트의 이름입니다. 커스텀 이벤트 이름의 string 일 수 있습니다. 예: "picture swiped".	예
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	안드로이드 / 구글 광고 ID입니다.	See Required Identifiers
user_data.android_id	안드로이드 하드웨어 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*	이벤트가 발생한 브라우저 또는 앱의 유저 에이전트입니다. 일반적으로 웹 뷰와 연결됩니다.	아니오
user_data.browser_fingerprint_id	브라우저 트래킹을 위한 Branch 내부 전용 필드입니다.	See Required Identifiers
user_data.http_origin	Web SDK가 웹 세션 시작을 로그한 현재 페이지 URL입니다.	아니오
user_data.http_referrer	Web SDK가 웹 세션 시작을 로그한 현재 페이지로 연결되는 참조 URL입니다.	아니오
user_data.developer_identity	유저의 개발자 지정 ID입니다.	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입니다. Export를 통해 검색되고 Webhook을 통해 전송되는 이벤트에 첨부됩니다.	아니오
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!

Overview

전제 조건

권한인증

API Usage

Logging Standard Events - Commerce, Content, User Lifecycle

엔드 포인트

Request Header Parameters

Request Body Parameters

❗️
Required Identifiers

요청의 예

Response Codes

커스텀 이벤트 로깅

엔드 포인트

Request Header Parameters

Request Body Parameters

❗️
Required Identifiers

예제 요청

Response Codes

Verify Events Sent

📘
Wait Period

필터

👍Try It!

Overview

전제 조건

권한인증

API Usage

Logging Standard Events - Commerce, Content, User Lifecycle

엔드 포인트

Request Header Parameters

Request Body Parameters

❗️Required Identifiers

요청의 예

Response Codes

커스텀 이벤트 로깅

엔드 포인트

Request Header Parameters

Request Body Parameters

❗️Required Identifiers

예제 요청

Response Codes

Verify Events Sent

📘Wait Period

👍
Try It!

❗️
Required Identifiers

❗️
Required Identifiers

📘
Wait Period