👍

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:

  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

엔드 포인트

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
경매의 경우 품목이 새롭거나 좋거나 무난한지 등의 여부.

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:

  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

성공

커스텀 이벤트 로깅

엔드 포인트

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

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.

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.