✕
필터
홈가이드
티켓 제출Branch 대시보드Branch UniversityLog In
티켓 제출Branch 대시보드Branch University

Webhook

Overview

Branch’s webhook system allows you to export install and down-funnel event data as it occurs. You can import this data into your internal systems for analysis. You simply need to specify a URL for the POST or GET requests.

If you are looking for postback integrations for ad networks, please visit our Universal Ads documentation. For pre-configured integrations into popular analytics tools, please visit our Data Integrations documentation.

Webhook 시스템은 커스터마이징이 가능합니다. 특정 이벤트나 이벤트의 특정 하위 섹션에 대해서, 또는 링크 데이터, 유저 데이터, 이벤트 프로퍼티로 필터링된 알림을 받도록 설정할 수 있습니다.

Our webhook infrastructure supports all Branch events. The data is formatted according to standard event naming and metadata format which will get you through implementation and on to analysis in no time.

📘

Data Feeds 솔루션은 프리미엄 솔루션입니다.

The Webhooks are included in Branch’s Data Feeds offering, which can be purchased according to Branch’s pricing schedule. Without Data Feeds, you can still export Branch data in CSV form directly from the Branch dashboard via Sources or CSV Exports.

Setup

Webhook 등록

  1. Open the Webhooks page on the Branch dashboard.
  2. + Add New Webhook 클릭:

Webhook 기준 설정

설정을 입력하면 다음 옵션이 표시됩니다.

  • Send a webhook to: 이벤트를 보낼 URL을 입력하세요. 이 URL은 Freemarker 구문으로 작성하여 파라미터를 동적으로 채우고 간단한 논리식을 실행할 수 있습니다. 아래에 Freemarker 서포트에 대한 자세한 정보가 있습니다.
  • using a GET/POST: 이벤트는 POST 또는 GET을 통해 보낼 수 있습니다. POST 이벤트는 기본 POST 바디로 생성됩니다. 아래에 POST 바디에 대한 자세한 정보가 있습니다.
  • users trigger event: 선택한 이벤트가 발생하면 웹훅이 실행됩니다.
이벤트설명
install유저가 디바이스에서 앱을 처음 실행하면 트리거됩니다.
reinstall유저가 디바이스에서 앱을 삭제하고 다시 설치하면 트리거됩니다.
open앱이 오픈될 때마다 트리거됩니다 (오픈이 설치 또는 재설치가 아닐 때).
web session start유저가 Branch Web SDK를 사용하여 웹 페이지를 볼 때 트리거됩니다.
click모든 플랫폼에서 Branch 링크를 클릭할 때마다 트리거됩니다.
-- additional events --Branch 웹 또는 앱 SDK를 통해 트래킹하는 전체 이벤트 목록입니다.

🚧

iOS 14.5 이후 설치 이벤트

Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in

옵트인은 최종 설치수 집계에 영향을 미칩니다. 다른 식별자 (예: IDFV)를 사용하여 내부 시스템에서 설치 이벤트의 중복을 제거하는 것이 좋습니다.

For additional information on changes post iOS 14.5, visit our FAQ Pages

📘

Pro Tip

지난 30일 동안 해당 이벤트 중 하나 이상이 기록된 경우에만 이벤트가 이벤트 드롭 다운에 표시됩니다.

For an exhaustive list of events and more detailed definitions of each event, please see the Event Ontology Data Schema.

🚧

이벤트 빈도

이벤트 빈도는 아직 지원되지 않습니다. 현재 웹훅은 이벤트가 발생할 때마다 전송됩니다.

기본 필터링

페이지의 Advanced 섹션에서 필터를 작성할 수 있습니다. 이 필터 기준에 맞는 이벤트만 전송됩니다.

NOTE: While Branch preserves the original case of all captured data field values and case is retained through export, when webhook/postback filters are evaluated, case-sensitivity is removed. For example, if you created a filter on user_data.os, iOS, ios, and IOS are equivalent.

이벤트가 알려진 크롤러/로봇에 의해 트리거 되지 않았는지 확인하는 기본 필터가 표시됩니다. 이를 위해 운영 체제가 "로봇"과 같지 않은지 확인합니다. 해당 필터를 적용하면 OS가 로봇과 같지 않은 이벤트(예: iOS 및 Android)만 웹훅을 트리거합니다.

The most popular filter options are available in a dropdown. This should help you get up and running quickly, while also providing an example structure for more advanced filtering if you need it.

필터를 생성하려면 :

  1. Add Filter 버튼을 클릭하십시오
  2. 필터링할 메타데이터를 선택합니다. 예를 들어 iOS 설치만 원하면 드롭 다운에서 "Operating System"을 선택합니다. 오른쪽에 있는 텍스트 필드가 올바른 키로 채워지는 것을 볼 수 있습니다. 나중에 고급 필터링을 수행할 때 "Custom" 을 선택하고 이 키를 수동으로 설정합니다.
  3. 다음 드롭 다운에서 "equals" 또는 "does not equal"을 선택합니다.
  4. 마지막으로, 필터하거나 출력하려는 키의 value 을 설정하십시오. 예를 들어, iOS가 설치되도록 하려면 드롭 다운에서 "을" 와 "IOS" 으로 설정해야 합니다. 이 예제에서는 로봇 필터가 중복되므로 빼기 단추를 사용하여 이를 제거하자.

저장하기 전 최종 화면은 아래와 같습니다:

📘

예: 어트리뷰션 링크 캠페인별로 설치 필터링

Campaign 필드를 App Install Campaign으로 설정한 Branch 링크에서 발생한 모든 install 이벤트에 대해 웹훅을 수신하고 싶은 상황을 가정해 보겠습니다. Campaign이 App Install Campaign과 같을 때만 웹훅을 실행하도록 필터를 설정합니다. 드롭 다운에서 Campaign을 선택하면 키가 자동으로 채워지고, 이는 last_attributed_touch_data.~campaign과 같습니다. 마지막으로 값을 App Install Campaign으로 설정합니다.

📘

예: 링크 채널별로 클릭 필터링

Channel 필드를 AppLovin으로 설정한 Branch 링크에서 발생한 모든 click 이벤트에 대해 웹훅을 수신하고 싶은 상황을 가정해 보겠습니다. Channel이 AppLovin과 같을 때만 웹훅을 실행하도록 필터를 설정합니다. 드롭 다운에서 Channel을 선택하면 키가 자동으로 채워지고, 이는 last_attributed_touch_data.~channel과 같습니다. 마지막으로 값을 AppLovin으로 설정합니다.

See the Advanced Filtering page to read more about customizing when events are sent.

Testing

To test whether your webhook is configured correctly, you can use RequestBin. RequestBin gives you a URL that accepts events for 24 hours and allows you to see exactly what Branch is sending.

  1. Go to RequestBin and click + Create Request Bin:

  1. Endpoint URL을 복사합니다.

  1. 이를 Branch 웹훅 설정 화면의 URL 필드에 붙여넣습니다.

  1. 이제 웹훅이 트리거 될 때마다 RequestBin에 대한 전체 보고서가 표시됩니다.

🚧

RequestBin

테스트가 끝나면 Requestbin 웹훅을 보관처리(archive)하세요. Requestbin은 24시간 동안만 지속되며 만료되면 오류를 반환합니다.

데이터 형식

고급 필터 또는 Freemarker 매크로를 설정하려면 Event Ontology 데이터 형식을 이해해야 합니다. 스키마를 살펴보기 전에 이벤트 메타데이터 구조에 대한 몇 가지 상위 레벨 개념을 이해해야 합니다.

  • 각 이벤트에는 "name" 및 "id"와 같은 최상위 레벨 필드가 있습니다.
  • 링크 데이터는 일반적으로 "Last Attributed Touch Data"
  • 유저 데이터(디바이스 및 OS 데이터 포함)는 "User Data"
  • 제품 또는 콘텐츠 레벨 데이터가 "Content Items"
  • 트랜잭션 및 일반 콘텐츠 데이터는 "Event Data"
  • Journeys 솔루션 또는 Deepviews 데이터 보기(예: 클릭이 아닌 Journeys 솔루션 배너 로드)는 "Last CTA View Data"
  • 클라이언트 지정 커스텀 데이터(예: 회사에서 특정 이벤트에 필요한 내부 필드)는 "Custom Data"

📘

사용 가능한 포스트백 매크로의 전체 목록

To find a complete list of Branch supported postback macros, please see Postback Macros & Functions.

🚧

IP와 위치정보의 불일치

IP로 위치를 분석할 수 없는 매우 적은 비율의 이벤트에 대해서는 국가 및 도시와 같은 지리 데이터를 사용하지 못할 수 있습니다.

Webhook POST 바디 구문 샘플

모든 웹훅의 POST 바디는 동일한 구조를 따릅니다.

POST
User-agent: Branch Metrics API
Content-Type: application/json
{
    "name": "<event name e.g. open>",
    "user_data": {},
    "last_cta_view_data": {},
    "last_attributed_touch_data": {},
    "custom_data": {},
    "event_data": {},
    "content_items": {},
    "timestamp": 'example timestamp (int)'
}

이러한 오브젝트가 비어 있으면 POST 바디에 나타나지 않습니다.

다음은 어트리뷰션된 오픈에 대한 예제 데이터가 있는 POST 바디입니다.

// Attributed open
POST
User-agent: Branch Metrics API
Content-Type: application/json

{
  "name": "open",
  "user_data": {
    "os": "IOS",
    "os_version": "11.1.2",
    "environment": "FULL_APP",
    "platform": "IOS_APP",
    "idfa": "F520B35A-4165-4426-98F6-64F12F47E9BZ",
    "idfv": "C6B869E7-7B0A-4A93-1C3D-960E8859DP5D",
    "limit_ad_tracking": false,
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_1_2 like Mac OS X) AppleWebKit/604.3.5 (KHTML, like Gecko) Mobile/15B202",
    "ip": "50.200.105.218",
    "developer_identity": "DB8C86A6-8B7C-4192-BD29-8107A5B788A1",
    "country": "US",
    "language": "EN",
    "brand": "Apple"
  },
  "last_cta_view_data": {
    "~id": 457624031399716729,
    "~campaign": "_test",
    "~feature": "journeys",
    "+domain": "branchster.app.link",
    "+url": "https://branchster.app.link/jeMczRn5XH",
    "$deeplink_path": "open/item/1234",
    "~creation_source": 5,
    "+referrer": "https://store.com/products/green-table",
    "foo": "bar",
    "$canonical_url": "https://store.com/products/green-table",
    "mydata": "set_branch_view_data_value",
    "~tags": [
      "tag1",
      "tag2",
      "bottom_banner_style"
    ]
  },
  "last_attributed_touch_data": {
    "~id": 467391383381228204,
    "~feature": "marketing",
    "~campaign": "december_test",
    "~channel": "Facebook Organic",
    "product_id": "XBA8198j",
    "product_name": "Green Table AB10",
    "+url": "https://branchster.app.link/test_linking",
    "$marketing_title": "Deep Link Testing",
    "$ios_deepview": "branch_default",
    "+via_features": [
      "QUICK_LINKS"
    ]
  },
  "custom_data": {
    "reinstall": "false",
    "ip": "50.200.105.218",
    "referred": "false"
  },
  "timestamp": 1512681005807
}

고급 필터링

In Basic Filtering we covered what filters do, and how to set basic filters. Branch supports more advanced filtering which allows customers to set filters based on almost any event metadata.

Make sure you've taken a look at the data format before you attempt to set advanced filters.

필터를 생성하려면 :

  1. Add Filter 버튼을 클릭하십시오
  2. 필터링할 메타 데이터를 선택합니다. 고급 필터링의 경우 "Custom"
  3. Type in the key that you'd like to filter on. To find the key you'd like to filter on, reference our quick introduction to the Br data format to figure out where your key is likely nested. Another foolproof way to find your key is looking at your data in full before setting up your filter. You can do this by doing a CSV export, API export or send a single webhook with a POST body, and locate your key in that POST body.
  4. 키가 상위 레벨 데이터의 일부가 아닌 경우 (예: timestamp 또는 id), 한 단계 더 깊이 들어가야 할 수 있습니다. 대부분의 키는 object_name.key 형식입니다. 예를 들어, "product_deeplink_id"이라는 딥링크(Deep Link) 데이터에서 커스텀 키를 필터링하려면 last_attributed_touch_data.product_deeplink_id 형식이 필요합니다.

📘

예: 특정 쿠폰에 대한 구매 필터링

Let’s say you’re interested in receiving a webhook for every Purchase event using a specific coupon. When you set up the Purchase event in your app or on your website, you added a specific piece of metadata for coupon. In the Event Ontology Schema you saw that coupon is inside event_data. To configure your filter to fire a webhook only when coupon is equal to SUMMERDEALS10 you will:

  1. 필터 키 드롭 다운에서 "Custom"을 선택하세요.
  2. 키 만들기 event_data.coupon
  3. 두번째 드롭 다운에서 "equals"를 선택합니다.
  4. 값을 입력하십시오. SUMMERDEALS10

🚧

배열(Array) 필터링은 아직 사용할 수 없습니다.

현재 웹훅은 배열 내의 값에 대한 필터링을 지원하지 않습니다. 값으로 필터링할 수 없는 배열의 예는 tags, +via_features 및 content_items입니다.

Postback URL 템플릿

Postback URL을 템플릿으로 만들고 싶다면, 앞에서 언급한 필터들을 따라 템플릿화된 Postback URL 중 하나를 생성해야 합니다. 이러한 작업은 필터와 매우 유사하지만 Freemarker 구문을 사용합니다.

템플릿 시작하기

시작하려면 간단한 템플릿을 추가 할 수 있습니다. 쿼리 파라미터로 캠페인을 추가한다고 가정해 보겠습니다. 올바른 구문은 다음과 같습니다.

`https://webhook.com?campaign=${(last_attributed_touch_data.~campaign)!}`

구문을 살펴보겠습니다.

  1. First, find the key for the value you want to template in. As with filtering, to find the key, reference our quick introduction to the Branch data format to figure out where your key is likely nested. Another foolproof way to find your key is looking at your data in full before setting up your filter. You can do this by doing a CSV export, API export or send a single webhook with a POST body, and locate your key in that POST body.
  2. This exercise tells us that Campaign is nested inside last_attributed_touch_data and is represented by last_attributed_touch_data.~campaign.
  3. The additional syntax around last_attributed_touch_data.~campaign is because Branch's templating engine uses Freemarker. In Freemarker, you can print variables by surrounding them with ${}. Finally, we add ()! to the variable because we want to prevent errors in the case that there is no value.
  4. This leaves us with ${(last_attributed_touch_data.~campaign)!}.

다음은 일반적인 템플릿에 대한 Freemarker의 예입니다.

부모 객체일반적인 이름Freemarker
BundleAndroid Package Name${(bundle.android.package_name)!}
BundleiOS Bundle ID${(bundle.ios.bundle_id)!}
Last Attributed Touch DataFeature${(last_attributed_touch_data.~feature)!}
Last Attributed Touch DataChannel${(last_attributed_touch_data.~channel)!}
Last Attributed Touch DataCampaign${(last_attributed_touch_data.~campaign)!}
Last Attributed Touch DataAd Partner Name${(last_attributed_touch_data.~advertising_partner_name)!}
User DataOS${(user_data.os)!}
User DataPlatform${(user_data.platform)!}
User Data애플 광고 식별자 (IDFA)${(user_data.idfa)!}
User DataIDFV${(user_data.idfv)!}
User DataAndroid 광고 ID${(user_data.aaid)!}

📘

사용 가능한 포스트백 매크로의 전체 목록

To find a complete list of Branch supported postback macros, please see Postback Macros & Functions.

Freemarker 표현식

보안 제한으로 인해 Branch는 Freemarker 표현식의 전체 목록을 지원하지 않습니다.

차단된 식 목록은 다음과 같습니다.

"<#import>", "<#visit>", "<#include>", "?eval", "<#recurse>", "<#setting>", "<#macro>", "<#function>", "<#nested>", "<#return>", "<#list>"

Allowlist webhook server IP addresses

  • If you need to allowlist the webhook server IP addresses for security purposes, they are listed below:
    • 52.9.159.121/32
    • 52.9.176.205/32
    • 52.9.188.221/32
    • 52.9.188.236/32
    • 52.52.143.205
    • 52.53.45.79
    • 52.8.3.171
    • 54.176.26.254

Webhook 이벤트 인증

To request authentication headers for your webhooks, please Submit a Ticket.

서포트

FAQ

Updated 7 days ago

What’s Next