코호트 동기화 연동 생성

코호트 동기화 연동을 구축하면 Amplitude 연동 포털이 Amplitude의 행동 코호트를 사용자 ID 목록 또는 사용자 지정 사용자 속성으로 귀하의 플랫폼에 전송하도록 설정되며, 그 구성을 Amplitude 고객이 활성화할 수 있는 목적지 타일로 패키지화합니다. 목적지 카탈로그에 사용자의 플랫폼에 대한 코호트 동기화 연동이 아직 없는 경우에만 새 연동을 구축하십시오. 존재하는 경우에는 이를 복제하지 않고 이를 사용하십시오.

이 가이드에서는 예제에 목록 기반 연동을 사용합니다. 속성 기반 코호트 동기화 연동을 구축하는 경우 몇 가지 단계가 다릅니다.

연동 설정

Amplitude가 연동을 검증한 후 Amplitude Destinations 페이지에 표시되는 연동 타일을 구성하십시오. 또한 목록 기반 코호트 연동과 속성 기반 코호트 연동 중 하나를 결정해야 합니다. 각 연동 유형에 대한 자세한 내용은 행동 코호트 수신하기를 참조하십시오.

1. 연동 포털 페이지(설정 > 개발자 포털)에서 새 목적지 추가를 클릭합니다.
2. 연결 정보 선택 드롭다운에서 대상 연결을 선택합니다.
3. 목록 기반 또는 속성 기반 코호트 연동 중 어느 것을 구축할 것인지 선택하십시오.
   • 목록 기반 코호트 연동: 목록 기반 코호트 연동은 대상 시스템이 코호트를 사용자 식별자 목록으로 나타내는 경우 가장 효과적입니다. 첫 번째 동기화에는 목록 생성 API에 대한 호출이 필요하며, 그 후에는 추가 API 및 제거 API에 대한 호출이 목록 멤버십을 최신 상태로 유지합니다.
   • 속성 기반 코호트 연동: 속성 기반 코호트 연동은 코호트 멤버십을 부울 플래그나 태그와 같은 사용자 정의 사용자 속성으로 표현하는 시스템에서 가장 잘 작동합니다. Amplitude는 코호트 멤버십이 변경될 때 업데이트 API를 호출하여 사용자 속성을 업데이트합니다. 목록 생성 API를 사용할 필요는 없지만 사용자 지정 사용자 속성을 수동으로 생성해야 할 수도 있습니다.
4. 다음을 클릭하여 목적지를 구성합니다.

연동 이름

연동 이름은 카탈로그 페이지에 나타납니다. 이름은 코호트 동기화 통합 전체에서 전역적으로 고유해야 합니다.

코호트 동기화 연동 구성

구성 페이지는 두 개의 섹션으로 구성됩니다.

• 구성 탭은 페이로드를 구성하고 Amplitude로부터 수신할 것으로 예상되는 내용을 구성하는 곳입니다.
• 테스트 연동 탭에는 연동, 변수 및 페이로드를 미리 볼 수 있는 목적지 설정 양식을 포함하여 구성이 요약됩니다. 이 탭에서 연동 기능을 테스트할 수도 있습니다.

다음 몇 섹션에서는 구성 및 테스트 옵션을 설명합니다.

인증 방법 설정

Amplitude와 귀사 대상 구간의 API 호출을 인증할 계획을 결정하십시오.

사용자 정의 헤더를 클릭하고 다음 옵션 중에서 선택합니다.

• 인증 없음: 이 옵션은 인증 헤더를 필요로 하지 않습니다.
• 기본 인증: API 키 및 API 암호(선택 사항)를 인증 헤더로 사용합니다.
• 인증 헤더: API 키를 사용하여 인증합니다.
• Bearer Token: Bearer Token을 Authorization 헤더로 사용합니다.

사용자 지정 필드 생성

이러한 필드는 API 호출 페이로드에 선언된 내용을 수집하고 $variable대체합니다. 또한 고객이 귀사의 연동을 활성화하기 위해 사용하는 모달도 구축합니다. 여기에서 추가하는 필드는 사용자가 연동을 설정할 때 필수 필드가 됩니다.

• 필드 유형: 문자열, 단일 선택 또는 단추 그룹과 같은 필드 유형을 지정합니다.
• 페이로드에 사용된 필드 변수 이름: 기본적으로 이 이름은 사용자의 인증 선택과 일치합니다. 예를 들어 인증 방법으로 Bearer Token을 선택할 경우 인증 방법은 bearer_token이 됩니다.
• 표시 이름: 사용자가 연동을 위한 설정 모달에서 볼 수 있는 이름입니다. 기본적으로 이 값은 사용자의 인증 선택과 일치합니다. 예를 들어 인증 방법으로 Bearer Token을 선택하면 "Bearer Token"이라는 플레이스홀더 표시 이름이 사용됩니다.
• 새 사용자 지정 필드 추가: 페이로드에 필요한 다른 식별자를 추가해야 하는 경우 문자열, 단일 선택 및 버튼 그룹과 같은 사용자 지정 필드를 추가할 수 있습니다.

맵 필드

필드를 매핑하여 Amplitude 필드가 시스템의 필드에 어떻게 연결되는지 지정합니다. 매핑 값은 페이로드의 item_template 을(를) 대체합니다.

연동 포털에서 매핑 필드를 구성할 때 연동 사용자는 목적지 설정에서 매핑 섹션을 확인합니다. 이 섹션에서는 사용자가 대상 시스템의 필드에 매핑할 Amplitude 사용자 속성을 선택할 수 있도록 합니다. 이 구성은 사용자 지정 사용자 식별자도 지원합니다.

• 매핑 필드 표시 이름: Amplitude는 이를 ‘키’, ‘식별자’ 또는 ‘사용자 ID 매핑’으로 설정할 것을 권장합니다.
• Amplitude 매핑 필드: Amplitude의 필드 이름입니다. 예를 들어 user_id_field_amplitude.
• 필드 유형: "문자열" 또는 "단일 선택" 중 하나입니다.
• 표시 이름: 이 이름은 완전히 사용자 지정할 수 있으므로 설명적인 이름을 사용하십시오. 예를 들어 사용자 ID 또는 이메일입니다.
• 새 매핑 추가: 필요한 경우 문자열, 단일 선택 또는 단추 그룹과 같은 매핑을 더 추가합니다.

Amplitude 코호트 이름 슬러그화

코호트 이름을 슬러그화하여 표준화할 수 있습니다. 이 옵션은 시스템이 특수 문자나 ASCII 문자가 아닌 문자를 지원하지 않는 경우에 유용합니다. 슬러그화는 유니코드 특수 문자와 스페이스를 ASCII 문자와 하이픈으로 바꾸어 코호트 이름을 URL 슬러그로 변환합니다. 이 기능은 $amplitude_cohort_name 변수가 엔드포인트 페이로드에 나타날 때만 작동합니다. 슬러그화 규칙은 다음과 같습니다.

• 원래 코호트 이름을 호환성 분해인 정규화 형식 KD(NFKD)로 변환합니다.
• 알파벳(a-z, A-Z), 숫자(0-9) 및 밑줄(_)을 제외한 모든 문자를 하이픈으로 대체하십시오.
• 슬러그를 100자로 제한하십시오.

목록 생성 엔드포인트

목록 기반 연동을 위해서는 세 가지 API를 호출해야 합니다. 첫 번째 API는 목록 생성 엔드포인트입니다. 코호트가 처음 데이터 동기화될 때, Amplitude는 이 API를 호출하여 플랫폼에 목록을 생성합니다. Amplitude는 앱이 listID에 대한 고유 식별자를 포함한 응답을 전송할 것으로 기대합니다. Amplitude는 해당 응답의 listID 저장하고 이 ID를 목록 업데이트용 페이로드의 일부로 사용합니다.

• URL 엔드포인트: https://api.yourapp.com/list 와 같은 엔드포인트를 정의합니다. 호출에 사용할 방법을 선택합니다.
• 목적지로 전송할 API 페이로드: 이 페이로드를 사용자 정의하여 필요에 맞게 하십시오.
• 응답에 포함된 목록 ID 경로: 해당 없음

목록 생성 엔드포인트에 대한 오류

모든 엔드포인트에 대한 오류 상태 코드와 오류 메시지를 추가하여 최종 사용자가 디버깅을 수행하고 더 신속하게 도움을 받을 수 있도록 합니다.

오류 분류를 확장하고 새 오류 추가를 클릭하여 상태 코드를 더 추가합니다. Amplitude는 상태 코드와 하위 오류 코드를 필요에 따라 많이 포함할 것을 권장합니다. 이러한 코드와 메시지는 최종 사용자의 디버깅을 더 빠르게 수행할 수 있도록 해줍니다.

1. Amplitude는 여러 오류에 대해 동일한 상태 코드를 사용하는 경우 하위 오류 코드를 사용할 것을 권장합니다.

다음은 대부분의 파트너가 포함하는 상태 코드의 일반적인 예입니다.

• 200: 성공
• 400: 잘못된 요청
• 401: 권한 없음(잘못된 요청api_key)
• 404: 잘못된 사용자 ID
• 429: 조절/속도 제한

Amplitude는 코호트 동기화가 실패할 경우 명확한 실패 이유(설명)와 오류 메시지를 제공할 것을 권장합니다. 명확한 메시지는 최종 사용자의 경험을 개선하고 지원 문제를 줄이는 데 도움이 될 수 있습니다.

사용자 엔드포인트 추가

Amplitude는 코호트가 Amplitude에서 앱으로 데이터 동기화될 때마다 사용자 추가 API를 호출합니다. 이 동기화는 매시간 또는 매일 실행될 수 있습니다. 이 호출은 현재 코호트 크기와 마지막으로 성공한 동기화 대상 구간의 차이를 계산합니다.

• URL 엔드포인트: URL에 $list_Id위치 표시자가 포함될 수 있지만 이 위치 표시자는 필수적인 것은 아닙니다. 대신 페이로드에 목록 ID를 배치하도록 API를 설계할 수 있습니다. 예: https://your.domain/lists/$listId/add.
• 목적지로 전송할 API 페이로드: 이 페이로드를 사용자 정의하고 페이로드가 배치인지 여부를 정의합니다. 해당 변수는 중요한 $items키입니다. _페이로드에서 변수를 대체하는 $items항목 배열_의 내용이 이 변수를 대체합니다.

이 $items 변수는 일반적으로 코호트의 모든 사용자를 식별합니다. 예를 들어 동기화가 진행되면 기존 코호트에 20명의 새로운 사용자가 추가될 수 있습니다. 배치 객체에는 20명의 사용자 목록과 같은 컬렉션이 포함되어 있으며, Amplitude는 이 20개의 객체를 엔드포인트로 전송합니다. 페이로드는 다음과 같을 수 있습니다.

json { "userIds": $items, "context": { "integration":{ "name": "Amplitude Cohort Sync", "version": "1.0.0" } } }

• 각 API 호출의 최대 항목 수(배치 크기): 기본값은 10,000이지만 이 값을 지정할 수 있습니다. Amplitude의 추천은 코호트 배치당 10,000명의 사용자를 확보하는 것입니다.
• 페이로드에서 $items변수를 대체하는 항목의 배열: 페이로드에서 $item변수를 대체하는 객체의 형식을 지정합니다. 예를 들어 "$user_id_field_amplitude".

가능하다면 속도 제한을 피하십시오. 초당 90 요청과 같은 속도 제한이 있는 경우 사용자 문서에 명시적으로 명시하십시오. Amplitude는 4개의 요청을 동시에 전송하며, 각 요청에는 최대 10,000명의 사용자가 포함됩니다.

사용자 엔드포인트 추가 오류

모든 상태 코드, 실패 이유, 오류 메시지 및 하위 오류 코드를 다시 생성하는 대신, Amplitude는 목록 생성 엔드포인트에서 동일한 오류 코드 세트를 사용할 것을 권장합니다. 다른 엔드포인트에서 오류 복사를 선택하고 오류가 구성된 엔드포인트를 선택합니다.

사용자 엔드포인트 제거

Amplitude는 코호트가 Amplitude에서 귀하의 앱으로 데이터 동기화될 때마다 사용자 제거 API를 호출합니다. 이 동기화는 매시간 또는 매일 실행될 수 있습니다. 이 호출은 현재 코호트 크기와 마지막으로 성공한 동기화 대상 구간의 차이를 계산합니다.

• URL 엔드포인트: URL에 $listId위치 표시자가 포함될 수 있지만 이 위치 표시자는 필수적인 것은 아닙니다. 대신 페이로드에 목록 ID를 배치하도록 API를 설계할 수 있습니다. 예: https://your.domain/lists/$listId/remove.
• 목적지로 전송할 API 페이로드: 이 페이로드를 사용자 정의하고 페이로드가 배치인지 여부를 정의합니다. 해당 변수는 중요한 $items키입니다. _페이로드에서 변수를 대체하는 $items항목 배열_의 내용이 이 변수를 대체합니다.

이 $items 변수는 일반적으로 코호트의 모든 사용자를 식별합니다. 예를 들어 동기화가 기존 코호트에서 20명의 사용자를 제거할 수 있습니다. 배치 객체에는 20명의 사용자 목록과 같은 컬렉션이 포함되어 있으며, Amplitude는 이 20개의 객체를 엔드포인트로 전송합니다. 페이로드는 다음과 같을 수 있습니다.

json { "userIds": $items, "context": { "integration":{ "name": "Amplitude Cohort Sync", "version": "1.0.0" } } }

• 각 API 호출의 최대 항목 수(배치 크기): 기본값은 10,000이지만 이 값을 지정할 수 있습니다. Amplitude의 추천은 코호트 배치당 10,000명의 사용자를 확보하는 것입니다.
• 페이로드에서 $items변수를 대체하는 항목의 배열: 페이로드에서 $item변수를 대체하는 객체의 형식을 지정합니다. 예를 들어 "$user_id_field_amplitude".

사용자 제거 엔드포인트 오류

모든 상태 코드, 실패 이유, 오류 메시지 및 하위 오류 코드를 다시 생성하는 대신, Amplitude는 목록 생성 엔드포인트에서 동일한 오류 코드 세트를 사용할 것을 권장합니다. 다른 엔드포인트에서 오류 복사를 선택하고 오류가 구성된 엔드포인트를 선택합니다.

엔드포인트 미리보기 및 테스트

검토를 위해 구성을 제출하기 전에 Amplitude로부터 수신할 것으로 예상되는 모의 페이로드를 테스트하십시오. 테스트 탭에서 다음 단계에 따라 구성을 미리 보고 테스트하십시오.

테스트 탭에서 목적지 설정 양식은 귀하의 연동 사용자가 보는 것과 일치합니다. 이 양식은 페이로드 헤더에 정의된 매개변수를 제어합니다.

사용자를 생성하려면 CSV를 업로드하거나 재생성을 클릭하여 설정에 따라 사용자를 생성하십시오. CSV에는 작업 열에 add또는 remove이 포함된 항목이 있어야 합니다. 목록 생성 페이로드에 사용되는 전체 매개변수는 CSV의 모든 행에서 동일해야 합니다. 또한 CSV에는 사용된 각 매개변수에 대한 열이 있어야 합니다.

다음은 기본 구성에 대한 샘플 CSV입니다.

operation,user_id_field_amplitude,amp_cohort_name,amp_cohort_id
add,user123,Unified Cohort,unified_cohort_001
add,user456,Unified Cohort,unified_cohort_001
remove,user789,Unified Cohort,unified_cohort_001
add,john.doe@example.com,Unified Cohort,unified_cohort_001

매개 변수 테이블을 확인하여 구성이 모든 변수를 고려하는지 확인하고 전체 오류를 해결하십시오. 선언된 모든 필드가 비어 있지 않은지 확인하십시오.

• 선언됨: "인증 호출, 사용자 지정 필드 및 매핑 필드" 섹션에 선언된 모든 변수입니다.
• 사용됨: 사용자 엔드포인트 목록, 사용자 엔드포인트 추가 및 사용자 엔드포인트 제거에 사용되는 모든 변수입니다.
• 미리 정의됨: Amplitude가 값을 대체하는 미리 정의된 변수입니다.

헤더를 수정하려면 구성 및 테스트 탭에서 목적지 설정 양식을 사용하십시오.

헤더와 페이로드를 확인하십시오. 준비가 되면 테스트 엔드포인트를 클릭하여 테스트 API 호출을 미리 정의된 엔드포인트로 전송합니다. 디버깅을 위해 응답 또는 오류가 나타납니다.

테스트 엔드포인트를 클릭한 후에는 성공 응답을 받아야 합니다. $list_id를 검색합니다. Amplitude는 $list_id를 "사용자 엔드포인트 추가"에 사용합니다.

{listId: $list_id}는 목록 생성 API 호출에 대한 예상 응답입니다. 구조를 변경하려면 목록 생성 구성의 _응답 값에서 목록 ID로 경로_를 변경하십시오.

검색한 $list_id을 사용하여 사용자 추가 및 사용자 제거 엔드포인트를 테스트하십시오.

테스트 연동 섹션의 테스트 엔드포인트 버튼을 사용하여 종단 간 테스트를 수행할 수도 있습니다. 이 버튼은 필요한 모든 테스트를 자동으로 실행합니다.

내부적 릴리즈

조직에서 테스트하려면 내부적으로 릴리스를 누릅니다. 이를 통해 조직 첫 사용 후 모든 사용자가 사용자가 정의한 연동을 사용할 수 있습니다. 연동은 즉시 사용할 수 있습니다.

연동 제출하기

테스트를 완료한 후 제출을 클릭하여 연동 작업을 Amplitude 팀에 제출하십시오. 검토 과정은 약 1 주일이 소요됩니다. Amplitude가 귀하의 연동을 승인하면 Amplitude는 귀하에게 이메일로 알림을 보내며 귀하의 연동 타일이 Amplitude의 목적지 섹션에 나타납니다.