이 페이지에서

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

코호트 웹후크

코호트 웹후크는 코호트 업데이트를 웹후크 엔드포인트에 전송합니다. 엔드포인트의 요구 사항에 따라 사용자 지정 데이터 보강, 필터링 또는 집계에 이 기능을 사용하십시오. 변환된 데이터를 마케팅 자동화 플랫폼이나 기타 시스템에 통합하여 최신 코호트 인사이트로 개인화된 캠페인을 지원하십시오.

고려 사항

  • 이 연동을 사용하려는 각 Amplitude 프로젝트에서 활성화하십시오.
  • 코호트 웹후크를 사용하려면 유료 Amplitude 플랜이 필요합니다.
  • 코호트 웹후크는 배치 추가 또는 제거 작업을 목적지로 전송합니다. 목적지는 각 배치를 1~2초 첫 사용 후 처리해야 하며(네트워크 지연 시간 포함), 이는 Amplitude가 재시도 제한 내에 200 OK 응답을 수신하도록 하기 위함입니다. 목적지가 제 시간에 응답하지 않으면 호출이 시간 초과되고 재시도되므로 중복된 페이로드가 생성될 수 있습니다.
  • Amplitude는 응답이 예상 기간 첫 사용 후 있는지 확인하기 위해 Postman과 같은 도구를 사용하여 목적지 엔드포인트 지연 시간을 테스트할 것을 권장합니다.
  • 처리 시간이 더 오래 걸리는 경우 즉시 200 OK를 반환하고 페이로드를 비동기식으로 처리하는 비동기 API 패턴을 사용하십시오(예: 인메모리 큐).

연동 설정

  1. Amplitude에서 웹후크로의 스트리밍을 구성하려면 다음 정보를 수집하십시오:

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

  2. 새 목적지를 생성합니다.

    1. Amplitude 데이터에서 카탈로그를 클릭하고 대상 탭을 선택합니다.
    2. 코호트 섹션에서 웹후크를 클릭하십시오.

  3. 웹후크의 URL 엔드포인트를 입력하십시오. 예를 들어, https://mycompany.com/webhook. Amplitude는 이벤트와 사용자를 전달하기 위한 단일 IP 주소를 가지고 있지 않으므로, 귀하의 URL은 모든 Amplitude 호스트의 페이로드를 허용해야 합니다.

  4. 모든 웹후크 동기화에는 두 개의 사전 설정된 헤더가 포함됩니다:

    • Content-Type: application/json
    • User-Agent: Amplitude/Webhook/1.0

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

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

  5. 웹후크에서 수신하고자 하는 페이로드를 정의하십시오. 다음과 같은 작업을 수행할 수 있습니다.

    1. Amplitude 코호트 형식을 따르는 기본 Amplitude 페이로드를 전송합니다.
    2. Apache FreeMarker 템플릿을 사용하여 페이로드를 사용자 정의합니다. 자세한 내용은 FreeMarker 템플릿 언어를 참조하십시오.

  6. 저장을 클릭하여 설정을 완료합니다.

목적지와의 코호트 데이터 동기화 설정

  1. Amplitude에서 내보낼 코호트를 엽니다.
  2. 동기화를 클릭하고 웹후크를 선택합니다.
  3. 정의된 웹후크 목적지를 선택하십시오.
  4. (선택 사항) 사용자와 함께 전달할 사용자 속성을 최대 50개까지 선택합니다. Amplitude는 선택한 속성을 사용자 페이로드에 추가하고 FreeMarker 템플릿에서 액세스할 수 있도록 합니다.
  5. 동기화 케이던스를 선택합니다.
  6. 동기화를 시작하려면 동기화를 클릭합니다.

FreeMarker 템플릿 언어

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

사용자 ID 전용 코호트 업데이트를 전송하기 위한 템플릿 예제

{
   "cohort_name": "${input.cohort_name}",
   "cohort_id": "${input.cohort_id}",
   "in_cohort": ${input.in_cohort?c},
   "computed_time": "${input.computed_time}",
   "message_id": "${input.message_id}",
   "users": [
   <#list input.users as user>
   {
      "user_id": "${user.user_id}"
   }<#sep>,
   </#list>
   ]
}

사용자 속성이 포함된 사용자 코호트 업데이트 전송을 위한 템플릿 예제

{
    "cohort_name": "${input.cohort_name}",
    "cohort_id": "${input.cohort_id}",
    "in_cohort": ${input.in_cohort?c},
    "computed_time": "${input.computed_time}",
     "message_id": "${input.message_id}",
    "users": [
     <#list input.users as user>
     {
         "user_id": "${user.user_id}",
         "user_properties": {
            <#list input.user_properties?keys as key>
                <#assign value = input.user_properties[key]>
                "${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#if key_has_next>,</#if>
            </#list>
        }
      }<#sep>,
     </#list>
]
}

사용자별로 코호트 업데이트를 전송하기 위한 템플릿 예제

일부 웹후크 목적지는 사용자 목록을 일괄 처리로 필요로 합니다. 다음 예제에서는 코호트 이름과 코호트 ID를 사용자가 코호트에 속해 있는지 여부를 나타내는 단일 부울 속성으로 설정합니다.

[ < #list input.users.iterator() as user > {
	'user_id': '${user.user_id}',
	'amplitude_${input.cohort_name}_${input.cohort_id}': $ {
		input.in_cohort
	}
} < #if user_has_next > , < /#if></#list > ]

템플릿 참조

  • FreeMarker는 ${ ... } 구문을 중괄호 안에 있는 표현식의 값으로 바꿉니다.
  • input 는 이벤트를 객체로 참조하는 예약된 변수입니다. 이 input 객체는 예제 페이로드와 동일한 형식을 따릅니다.
  • input 객체는 다음과 같은 형식을 갖습니다.
    • cohort_name 문자열입니다. 코호트의 표시 이름입니다.
    • cohort_id 문자열입니다. 코호트의 고유 식별자입니다.
    • in_cohort 부울값입니다. 이 사용자 배치가 코호트에 들어오는지 아니면 나가는지 여부를 나타냅니다.
    • computed_time 문자열입니다. Amplitude가 이 업데이트를 계산한 시간은 Unix 에포크 시간(초)으로 표시됩니다(예: "1692206763").
    • message_id 문자열입니다. 이 업데이트 메시지의 고유 식별자입니다. 이 값을 사용하여 재시도 시 중복 제거를 수행하십시오.
    • users JSON 객체의 목록입니다. 사용자 페이로드입니다.
      • user_id 문자열입니다. 사용자의 Amplitudeuser_id입니다.
      • user_properties JSON 객체입니다. 이 코호트 동기화 다음 기간동안 이 사용자에 대해 선택된 사용자 속성입니다.

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