웹후크 스트리밍

Amplitude의 웹후크 연동을 통해 Amplitude 이벤트와 사용자를 맞춤형 웹후크로 전달할 수 있습니다. 이는 Amplitude에서 선택한 URL로 이벤트 및 사용자 데이터 스트림을 전송하는 가벼운 방법입니다.

활용 사례

워크플로 자동화: 웹후크는 지정된 이벤트나 조건에 따라 동작을 트리거함으로써 워크플로를 자동화하고 이질적인 시스템을 연결합니다. 예를 들어 사용자 동의의 캡처 및 기록을 자동화하기 위한 웹후크를 생성하십시오. 사용자가 서비스 약관에 동의하면 웹후크가 트리거되고 Amplitude는 해당 이벤트를 기록합니다.
표준 스트리밍 통합을 뛰어넘는 유연성: 웹후크는 표준 스트리밍 통합을 뛰어넘는 사용자 지정 기능을 제공하므로 실시간 데이터 교환과 맞춤형 상호 작용을 가능하게 합니다. 예를 들어 웹후크를 사용하여 Amplitude에서 Braze로 특정 이벤트 데이터를 전송할 수 있습니다. 이 사용 사례는 네이티브 Amplitude Braze 스트리밍 연동에서 지원되지 않습니다. 여기에는 market와 newsletter_names를 포함하는 배열인 newsletters이라는 Amplitude 사용자 속성을 Braze에 적합한 형식으로 변환하는 작업이 포함됩니다.

연동 설정

사전 조건

Amplitude에서 웹후크로의 스트리밍을 설정하려면 다음 정보가 필요합니다.

웹후크 URL: Amplitude가 이벤트와 사용자를 전송하는 데 사용해야 하는 목적지 URL입니다.
헤더 정보: 웹후크 요청에 대해 최대 5개의 추가 헤더를 설정할 수 있습니다.

새 동기화 생성

Amplitude 데이터에서 카탈로그를 클릭하고 대상 탭을 선택합니다.
'웹후크'를 검색하고 웹후크: 이벤트 · 사용자 속성을 선택합니다.
동기화 이름을 입력한 다음 동기화 생성을 클릭합니다.

웹후크 URL 입력

웹후크의 URL 엔드포인트를 입력하세요. 예를 들어, https://mycompany.com/webhook. Amplitude는 이벤트와 사용자를 전달하기 위한 단일 IP 주소를 가지고 있지 않으므로, 귀하의 URL이 전체 Amplitude 호스트로부터 페이로드를 수신할 수 있는지 확인하세요.

웹후크 호출이 실패할 때 발생하는 상황에 대한 자세한 내용은 Amplitude의 재시도 메커니즘을 참조하세요.

헤더 선택

모든 웹후크 동기화에는 두 가지 사전 설정 헤더가 있습니다.

Content-Type, application/json
User-Agent, Amplitude/Webhook/1.0

이러한 사전 설정된 헤더 이후에 5개의 헤더를 더 정의할 수 있습니다. 새 헤더를 생성하려면 다음과 같이 하십시오.

왼쪽 텍스트 상자에 헤더 이름을 입력합니다.
오른쪽 텍스트 상자에 헤더 값을 입력합니다.
제한에 도달하지 않은 경우 새 헤더 행이 나타납니다.

이벤트 전달 구성

이벤트 보내기에서 토글("이벤트가 웹후크로 전송됨")을 활성화하여 이벤트를 웹후크로 스트리밍합니다. 활성화된 경우 Amplitude는 이벤트를 수집할 때 자동으로 웹후크에 전달합니다. 이 연동은 일정에 따라 또는 필요에 따라 이벤트를 전송하지 않습니다.

웹후크에서 수신하고자 하는 이벤트 페이로드를 정의하세요. 다음 작업을 선택할 수 있습니다.
1. Amplitude 이벤트 형식을 따르는 기본 Amplitude 페이로드를 전송합니다.
2. Apache FreeMarker 템플릿을 사용하여 페이로드를 사용자 정의합니다. FreeMarker 템플릿 언어 섹션을 참조하십시오.
이벤트 선택 및 필터링에서 전송할 이벤트를 선택합니다. 웹후크에서 필요한 이벤트만 선택하세요. 이 연동은 변환된 이벤트를 지원하지 않습니다.

사용자 전달 구성

사용자 보내기에서 토글("사용자가 웹후크로 전송됨")을 활성화하여 사용자와 해당 속성을 웹후크로 스트리밍합니다. 활성화된 경우 Amplitude는 이벤트를 수신할 때 사용자를 웹후크로 보냅니다. 또한 Amplitude는 Amplitude Identify API 호출을 웹후크로 전달합니다. 이 연동은 일정에 따라 또는 필요에 따라 사용자를 전송하지 않습니다.

웹후크에서 수신하고자 하는 사용자 페이로드를 정의하세요. 다음 작업을 선택할 수 있습니다.
1. Amplitude 사용자 형식을 따르는 기본 Amplitude 페이로드를 전송합니다.
2. Apache FreeMarker 템플릿을 사용하여 페이로드를 사용자 정의합니다. FreeMarker 템플릿 언어 섹션을 참조하십시오.

동기화 활성화

구성에 만족하면 페이지 상단에서 상태를 "활성화됨"으로 전환하고 저장을 클릭하십시오.

Amplitude의 재시도 메커니즘

Amplitude는 각 이벤트 또는 사용자에 대해 먼저 전송을 시도합니다. 실패 시 Amplitude는 오류와 관계없이 4시간 동안 9번의 시도를 더 수행합니다. 또한 Amplitude는 5xx 오류와 429 스로틀링에 대해 각 시도 첫 사용 후 재시도 메커니즘을 갖추고 있습니다. Amplitude는 다음 정책을 사용하여 즉시 재시도를 시도합니다.

최대 시도 횟수: 3.
초기 대기 시간이 100ms인 기하급수적 재시도이며, 매번 두 배로 증가하며 지터는 50%입니다.
Amplitude는 4초 후에 다시 시도하지 않습니다.

FreeMarker 템플릿 언어

Amplitude는 Apache FreeMarker 템플릿을 사용하여 웹후크에 전송하는 이벤트 페이로드를 사용자 지정합니다.

FreeMarker 템플릿 언어(FTL)를 사용하여 Amplitude의 이벤트와 사용자 페이로드를 웹후크 목적지가 기대하는 순서 무관 JSON 스키마로 변환할 수 있습니다.
Amplitude의 이벤트 형식입니다.
Amplitude의 사용자 형식입니다. Identify API를 사용하는 방법에 따라 일부 필드가 다를 수 있습니다(예를 들어, ID 호출에서 user_id을 대신 사용하는 경우 페이로드에 device_id가 포함되지 않습니다)user_id.

더 많은 FreeMarker 도움말.

자세한 도움말은 템플릿 만들기에 대한 FreeMarker 안내서를 참조하십시오.

이벤트 전송을 위한 템플릿 예제

text

{
      <#if input.user_id??>
      "external_id" : "${input.user_id}",
      </#if>
      "name" : "${input.event_type}",
      "time" : "${input.event_time}",
      "properties" : {
            "email" : "${input.user_properties.email!}"
      }
}

이 템플릿을 사용하면 다음 JSON 페이로드가 웹후크 엔드포인트로 전송됩니다.

json

{
    "external_id" : "some user id", // if `input.user_id` exists
    "name" : "click event",
    "time" : "2022-10-24T20:07:32.123",
    "properties" : {
        "email" : "some@email.com"
    }
}

사용자를 보내는 데 사용되는 템플릿 예제

text

{
      <#if input.user_id??>
      "external_id" : "${input.user_id}",
      </#if>
      <#if input.device_id??>
      "device_id" : "${input.device_id}",
      </#if>
      "time" : "${input.event_time}",
      "properties" : {
            "email" : "${input.user_properties.email!}"
      }
}

이 템플릿을 사용하면 다음 JSON 페이로드가 웹후크 엔드포인트로 전송됩니다.

json

{
    "external_id" : "some user id", // if `input.user_id` exists
    "device_id" : "some user id", // if `input.user_id` exists
    "time" : "2022-10-24T20:07:32.123",
    "properties" : {
        "email" : "some@email.com"
    }
}

이벤트 시간 형식 처리

Amplitude는 기본적으로 시간을 UTC ISO-8601 형식의 문자열(예: "2022-02-28 20:07:01.795")로 전송합니다.

이를 다른 형식으로 수정하려면 다음과 같이 하십시오.

먼저 날짜/시간 형식을 설정합니다. <#setting datetime_format="yyyy-MM-dd HH:mm:ss.S">
다음 예제를 사용하여 다른 시간 형식으로의 전환에 활용하십시오.
- 사용자 정의 문자열 형식: "${input.event_time?datetime?string["dd.MM.yyyy, HH:mm"]}"
  - 결과: "28.02.2022, 20:07"
- 밀리초 타임스탬프: "${input.event_time?datetime?long}"
  - 결과: "1646107621000"

템플릿에 대한 기타 유용한 정보

FreeMarker는 ${ ... }구문을 중괄호 안에 있는 표현식의 실제 값으로 바꿉니다.
input 는 이벤트를 객체로 참조하는 예약된 변수로, 이는 내보내기 API 문서에 정의되어 있습니다.
input.event_type 는 이벤트의 event_type필드를 나타냅니다.
input.user_properties 는 사용자 속성 사전을 나타냅니다.
input.user_properties.email 는 사용자 속성의 email필드를 나타냅니다.
if지시어는 필드가 존재하는지 확인합니다. 그렇지 않은 경우 FreeMarker는 출력에서 해당 필드를 생략합니다.
input.user_properties.email에 해당 필드가 없는 경우 표현식 뒤의 !표시에는 기본값이 포함됩니다input. 기본값을 추가하지 않으면 출력에는 대신 빈 문자열이 포함됩니다.

이 내용이 도움이 되었나요?