Webhook

Overview

사용자 중심 어트리뷰션을 위한 Branch의 웹훅 시스템을 사용하면 설치 및 다운 퍼널 이벤트 데이터가 발생하는 시점에 데이터를 추출할 수 있습니다. 분석을 위해 이 데이터를 내부 시스템으로 가져갈 수도 있습니다. POST 또는 GET 요청에 대한 URL을 지정하기만 하면 됩니다.

애드 네트워크에 대한 포스트백 연동을 찾고 있다면 Universal Ads(광고 어트리뷰션) 참조문서를 방문하세요. 널리 사용되는 분석 도구에 사전 구성된 연동을 보려면 Data Integrations 참조문서를 방문하세요.

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

새로운 Webhook 인프라는 모든 Branch 이벤트를 지원합니다. 데이터는 업데이트된 이벤트 이름 지정 및 메타 데이터 형식에 따라 형식이 지정되어 즉시 구현 및 분석을 수행할 수 있습니다.

📘

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

웹훅은 Branch의 가격 책정 스케줄에 따라 구매할 수 있는 Branch의 Data Feeds(데이터 연동) 오퍼링에 포함되며, Journeys(웹-투-앱 스마트배너), Universal Email(이메일-투-앱) 또는 Universal Ads(광고 어트리뷰션)에 대한 Launch 및 Startup 플랜에 있는 고객에게는 추가 비용 없이 사용 가능합니다. 데이터 요금이 없으면 Sources 또는 CSV 추출을 통해 Branch 대시보드에서 직접적으로 Branch 데이터를 CSV 형식으로 추출할 수 있습니다.

Setup

Webhook 등록

  1. Branch 대시보드에서 Webhooks 페이지를 오픈합니다.
  2. + Add New Webhook 클릭:

imageimage

Webhook 기준 설정

imageimage

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

  • 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은 AppTrackingTransparency 프레임워크를 통해 디바이스 데이터 공유에 대한 유저 동의를 받도록 요구합니다. 설치가 유료 광고를 통해 발생되었을 때, 첫 번째 설치는 오가닉으로 기록되며, 유저 동의 후 두 번째 설치 이벤트가 기록되고 해당 유료 광고로 어트리뷰션 됩니다.

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

iOS 14.5 이후의 변경 사항에 대한 추가 정보는 FAQ 페이지를 참조하십시오

📘

Pro Tip

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

전체 이벤트 목록과 각 이벤트에 대한 자세한 정의는 Event Ontology Data Schema를 참조하세요.

🚧

이벤트 빈도

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

기본 필터링

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

참고: Branch는 캡쳐된 모든 데이터 필드 값의 기존 대소문자를 유지하고 Export를 통해 추출시에는 대소문자가 유지되지만, 웹훅/포스트백의 필터링 적용 시에는 대소문자 구분이 제거됩니다. 예를 들어 user_data.os, iOS, ios, IOS로 필터를 만든 경우 모두 동일하게 인식합니다.

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

가장 많이 사용되는 필터 옵션은 드롭 다운에서 사용할 수 있습니다. 이렇게 하면 빠르게 시작하고 실행하는 데 도움이되며 필요한 경우 고급 필터링을 위한 예제 구조도 제공됩니다.

필터를 생성하려면 :

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

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

imageimage

📘

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

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

imageimage

📘

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

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

imageimage

이벤트 전송시기 커스터마이징에 대한 자세한 내용은 Advanced Filtering 페이지를 참조하세요.

Testing

웹훅이 올바르게 설정되었는지 테스트하려면 RequestBin 을 사용할 수 있습니다. RequestBin은 24시간 동안 이벤트를 수락하는 URL을 제공하며 Branch가 보내는 내용을 정확히 확인할 수 있습니다.

  1. RequestBin으로 이동하여 + 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"

📘

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

Branch 지원 포스트백 매크로의 전체 목록을 찾으려면 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
}

고급 필터링

Basic Filtering에서는 필터의 기능과 기본 필터를 설정하는 방법에 대해 설명했습니다. Branch는 고객이 거의 모든 이벤트 메타 데이터를 기반으로 필터를 설정할 수 있는 고급 필터링을 지원합니다.

고급 필터를 설정하기 전에 데이터 형식을 살펴보세요.

필터를 생성하려면 :

  1. Add Filter 버튼을 클릭하십시오
  2. 필터링할 메타 데이터를 선택합니다. 고급 필터링의 경우 "Custom"
  3. 필터링할 키를 입력하세요. 필터링할 키를 찾으려면 사용자 중심 어트리뷰션의 데이터 형식에 대한 간략한 소개를 참조하여 키가 중첩될 가능성이 있는 위치를 확인하세요. 키를 찾는 또 다른 안전한 방법은 필터를 설정하기 전에 데이터 전체를 살펴보는 것입니다. CSV 내보내기, API 내보내기를 수행하거나 POST 바디가 있는 단일 웹훅을 전송하여 이 작업을 수행하고 해당 POST 바디에서 키를 찾을 수 있습니다.
  4. 키가 상위 레벨 데이터의 일부가 아닌 경우 (예: timestamp 또는 id), 한 단계 더 깊이 들어가야 할 수 있습니다. 대부분의 키는 object_name.key 형식입니다. 예를 들어, "product_deeplink_id"이라는 딥링크(Deep Link) 데이터에서 커스텀 키를 필터링하려면 last_attributed_touch_data.product_deeplink_id 형식이 필요합니다.

📘

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

특정 쿠폰을 사용하여 Purchase 이벤트마다 웹훅을 수신하는 데 관심이 있다고 가정해 보겠습니다. 앱이나 웹 사이트에서 구매 이벤트를 설정할 때 coupon에 대한 특정 메타 데이터를 추가했습니다. Event Ontology Schema에서 couponevent_data 안에 있음을 확인했습니다. couponSUMMERDEALS10와 같을 때만 웹훅을 실행하도록 필터를 구성하려면 다음을 수행합니다.

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

imageimage

🚧

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

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

Postback URL 템플릿

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

템플릿 시작하기

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

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

구문을 살펴보겠습니다.

  1. 먼저 템플릿에 넣을 값의 키를 찾으세요. 필터링과 마찬가지로 키를 찾으려면 사용자 중심 어트리뷰션의 데이터 형식 에 대한 빠른 소개를 참조하여 키가 중첩될 가능성이 있는 위치를 파악하세요. 키를 찾는 또 다른 안전한 방법은 필터를 설정하기 전에 데이터 전체를 살펴보는 것입니다. CSV 내보내기, API 내보내기를 수행하거나 POST 바디가 있는 단일 웹훅을 전송하여 이 작업을 수행하고 해당 POST 바디에서 키를 찾을 수 있습니다.
  2. 이를 통해 Campaign이 last_attributed_touch_data안에 포함되고 last_attributed_touch_data.~campaign로 표시됨을 알 수 있습니다.
  3. last_attributed_touch_data.~campaign 주변의 추가 구문은 Branch의 템플릿 엔진이 Freemarker를 사용하기 때문입니다. Freemarker에서 변수를 ${}으로 묶어 인쇄 할 수 있습니다. 마지막으로 값이 없는 경우 오류를 방지하기 위해 변수에 ()!를 더합니다.
  4. 결과적으로 ${(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)!}

📘

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

Branch 지원 포스트백 매크로의 전체 목록을 찾으려면 Postback Macros & Functions를 참조하세요.

Freemarker 표현식

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

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

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

Webhook 서버 IP 주소 화이트리스트

  • 보안을 위해 Webhook 서버 IP 주소를 화이트리스트에 추가해야 하는 경우 다음과 같습니다.
    • 52.9.159.121/32
    • 52.9.176.205/32
    • 52.9.188.221/32
    • 52.9.188.236/32

Webhook 이벤트 인증

웹훅에 대한 인증 헤더를 요청하려면 Submit a Ticket을 참조하세요.

서포트

FAQ

Updated 5 months ago


다음 단계

Webhook FAQ

Webhook


제안된 편집은 API 참조 페이지에서 제한됩니다.

Markdown 본문 콘텐츠에 대한 편집만 제안할 수 있지만 API 사양에는 제안할 수 없습니다.