이벤트 스트리밍 연동 생성

이벤트 스트리밍 연동은 이벤트가 발생할 때 이벤트를 Amplitude 외부의 목적지로 실시간 전달합니다. 플랫폼이 Amplitude의 이벤트 데이터를 수신해야 할 때 이러한 유형의 연동을 구축하십시오. 대신 이벤트 데이터를 Amplitude로 전송하려면 이벤트 수집 연동을 구축하십시오.

이벤트 스트리밍 고려 사항

지원되는 기능

• 이벤트 전달: 이벤트 전달은 Amplitude Track 호출을 목적지로 전송합니다. Amplitude는 원시 이벤트와 병합되거나 변환된 이벤트를 모두 전달합니다. 또한 Amplitude는 event_name 및 created_at를 목적지로 전송합니다.
• 이벤트 필터링: Amplitude에는 사용자가 선택한 이벤트 유형과 속성 조건을 기반으로 전송할 이벤트를 선택할 수 있는 세부적인 필터링 옵션이 있습니다.
• 이벤트 선택적 속성 전달: 사용자는 전달된 이벤트의 페이로드에 포함시킬 이벤트, 사용자 또는 그룹 속성을 선택할 수 있습니다.
• 일반 사용자 식별 전달(사용자 생성 및 업데이트): 목적지에 대해 식별 전달 기능을 활성화합니다. 이 기능을 사용하면 목적지가 Identify API에서 생성된 사용자와 해당 속성을 실시간으로 전송할 수 있습니다. 자세한 내용은 Identify 설명서를 참조하십시오.
• 사용자 속성 매핑: 사용자는 Amplitude 사용자 속성을 선택하여 목적지의 필드에 매핑할 수 있습니다. 이 구성은 사용자 지정 사용자 식별자도 지원합니다.

이벤트 스트리밍 제한 사항

• 사용자 선택적 속성 전달: Amplitude는 허용 목록을 기반으로 이벤트에서 특정 이벤트, 그룹 또는 사용자 속성을 전달하는 것을 지원하지 않습니다.
• 배열 또는 객체 유형 속성 전달: 배열 또는 객체 유형 속성을 전달할 수 없습니다. 예를 들어, 도시의 배열인 cities속성을 전달할 수 없습니다.
• 변경 기반 사용자 Identify 전달: Amplitude는 이벤트 수집 중에 사용자 속성이 변경될 때 Identify 이벤트를 자동으로 생성하여 전달하지 않습니다.
• 속성 값 트랜스포메이션: 원래 이벤트 유형을 모르는 경우 속성 값이나 유형을 다른 값이나 유형으로 변환할 수 없습니다.
• 선택적 속성 전달 유형: Amplitude는 사용자가 전달한 모든 사용자 지정 속성을 문자열로 전송합니다.
• OAuth 인증: Amplitude는 OAuth를 지원하지 않으므로 파트너는 API 키를 생성해야 합니다.
• 이벤트 범주 이름: Amplitude는 이벤트 범주 이름을 전송하지 않습니다.

이벤트 스트리밍 엔드포인트 준비

1. Freemarker: Amplitude가 이벤트를 전송하는 데 사용하는 템플릿 엔진인 Freemarker에 대해 잘 알고 있어야 합니다.
2. 속도 제한: 속도 제한을 가능한 한 높게 설정하여 속도 조절을 최소화하십시오. 예를 들어 Amplitude는 Braze가 통신하는 속도 제한(이벤트 트래킹을 위해 분당 50,000건의 요청)을 준수합니다. Amplitude에는 4시간 동안 9번 시도하는 기하급수적 백오프가 포함된 재시도 메커니즘이 있습니다. 이 프로세스를 통해 일시적인 쓰로틀링 문제를 해결할 수 있습니다.
3. 이벤트 제한: 이벤트 크기 제한이 고객 사용 사례에 충분히 유연한지 확인하십시오.

4. 인증 방법: Amplitude는 OAuth를 지원하지 않으므로 파트너는 API 키를 생성해야 합니다.
5. 종단점 유연성: Amplitude는 특정 형식의 객체 목록을 생성합니다. 엔드포인트가 이 페이로드 구조를 처리하는지 확인하십시오. 페이로드 예제는 다음 섹션을 참조하십시오.

연동 설정

Amplitude의 목적지 페이지에 표시되는 연동 타일을 구성합니다.

1. 연동 포털 페이지(설정 > 개발자 포털)에서 새 목적지 추가를 클릭합니다.
2. 목적지 유형 선택에서 이벤트 스트리밍을 선택합니다.

설정 모드의 예제

Amplitude에서 완료된 설정 모달의 예를 보려면 Amplitude에서 _Data Destinations_로 이동한 다음 Event Streaming으로 표시된 연동을 추가하십시오.

이벤트 스트리밍 연동 구성

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

• 구성 탭은 페이로드를 구성하고 Amplitude로부터 수신할 것으로 예상되는 내용을 구성하는 곳입니다.
• Testing 탭에는 연동, 매개변수 및 페이로드에 대한 설정 모달 화면을 포함하여 구성이 요약되어 있습니다. 이 탭을 사용하면 사용자 지정 페이로드를 사용하여 구성을 테스트할 수도 있습니다.

연동 이름

연동 이름은 카탈로그 페이지에 나타납니다. 이름은 이벤트 스트리밍 통합 전체에서 전역적으로 고유해야 합니다.

매개변수 작성

이 섹션에서는 URL, 헤더 및 이벤트 본문에서 사용할 수 있는 매개 변수를 정의할 수 있습니다.

• 매개변수 표시 이름: 이 이름은 완전히 사용자 정의할 수 있으므로 설명적인 이름을 사용하십시오. 이 값은 Amplitude의 표시 이름입니다. 예를 들어 'REST API 엔드포인트 및 REST API 키'입니다.
• 매개변수 이름: 페이로드, URL 또는 헤더는 해당 매개변수에 대해 이 ID를 사용합니다.

사용자 속성 매핑 사용자 정의

이 섹션에서는 사용자가 선택한 Amplitude 사용자 속성으로 채울 수 있는 페이로드의 필드를 정의할 수 있습니다. 예를 들어 대부분의 목적지는 사용자 식별자로 여기에 필드를 사용하고 이를 필수 항목으로 설정합니다.

• 목적지 속성 이름: 필드 이름과 표시 이름 모두로 사용됩니다.
• 필수 확인란: 이 옵션을 선택하면 사용자가 이 필드를 구성할 때까지 이벤트를 목적지로 전달할 수 없습니다.

이벤트 페이로드 사용자 지정

Customize Events Payload 섹션을 사용하여 페이로드에 포함되는 내용을 사용자 정의할 수 있습니다.

• URL 엔드포인트: 엔드포인트에 따라 PUT, POST 또는 PATCH를 선택할 수 있습니다.
• REST API 헤더: 사용 사례에 맞게 API 헤더 유형을 사용자 정의할 수 있습니다. 예를 들어 다음과 같습니다.
  • 인증: HTTP 인증을 위한 인증 자격 증명을 포함합니다.
  • Content-Type: 클라이언트에게 application/json또는 application/javascript과 같은 응답 미디어 유형을 알려줍니다. 이 헤더는 클라이언트가 응답 본문을 올바르게 처리하는 데 도움을 줍니다.
  • WWW-Authenticate: 서버는 요청된 자원에 응답하기 전에 인증이 필요할 경우 이 헤더를 초기 응답으로 전송할 수 있습니다. 이 헤더는 종종 401 응답 코드와 함께 나타납니다. 이는 "권한이 없음"을 의미합니다.
  • Accept-Charset: 요청은 이 헤더를 설정하고 서버에게 UTF-8, ISO-8859-1 또는 Windows-1251과 같은 클라이언트가 허용할 수 있는 문자 집합을 알려줍니다.
  • Cache-Control: 서버는 이 응답에 대한 캐시 정책을 정의합니다. 클라이언트는 캐시된 응답을 저장하고 Cache-Control 헤더가 만료될 때까지 이를 재사용합니다.
• 헤더 키 및 헤더 값: 이 값은 완전히 사용자 지정이 가능하므로 설명적인 내용을 사용하세요. 예를 들어 'API 키'입니다. 이 값은 페이로드에 포함되지 않습니다.

페이로드 구조의 예

{
  "external_id": "some user id",
  "app_id": "some app id",
  "name": "test_event_type",
  "time": "2022-01-06T17:29:04Z",
  "optional_property": "some Amplitude property",
  "optional_property_again": "some Amplitude property again",
  "properties" : {
        "test_nested_property": "some nested property",
        "library": "some library",
        "user_property_1": "some user property value 1"
  },
},

이벤트 본문 편집기

이 섹션은 Freemarker 템플릿으로, 목적지로 전송되는 페이로드를 구성할 수 있습니다. 스크린샷의 템플릿은 사용자가 동기화를 구성하는 방법과 사용자 속성 매핑 사용자 지정 섹션에 따라 예제 페이로드 구조와 일치할 수 있습니다.

• 입력: 이 객체에는 전달된 이벤트와 해당 필드가 포함됩니다. Amplitude는 사용자의 다른 이벤트와 사용자 속성으로 객체를 풍부하게 해줍니다. 이러한 필드는 보장되지 않으며 각 사용자가 이벤트를 계측하는 방법에 따라 달라집니다. Amplitude는 입력 필드 사용량을 최소화하고 user_id, event_type및 event_time과 같은 일반적인 필드를 사용하도록 제안합니다.
• 매개변수: 키-값 쌍으로, 여기서 키는 매개변수 생성 섹션에 정의된 매개변수 이름입니다. 이 값은 동기화를 설정할 때 사용자가 제공한 값에 해당합니다.
• MappedProperties: 고객이 목적지로 전달하려는 이벤트, 사용자 또는 그룹 속성의 키-값 쌍입니다. 예를 들어 고객이 email: example@example.com속성을 추적하고 해당 속성을 귀하의 플랫폼으로 전달하려고 할 수 있습니다. Amplitude는 사용자가 UI의 전송할 이벤트 속성 지정 아래에서 해당 속성을 선택한 경우에만 이러한 속성을 전달합니다.
• MappedFields: 키-값 쌍으로, 여기서 키는 사용자 속성 매핑 사용자 정의 섹션에 지정된 목적지 속성 이름입니다. 이 값은 사용자가 UI의 [매핑] 탭 아래에서 선택한 Amplitude 속성의 값에 해당합니다. 예를 들어 필드로 지정했을 external_id수 있으며 사용자가 UI에서 Amplitude 속성을 선택했을 email: example@example.com수 있습니다. 그러면 MappedFields은(는) 키-값 쌍입니다: {external_id: example@example.com}.

미리 보기 및 테스트

1. 검토를 위해 구성을 제출하기 전에 테스트 탭에서 Amplitude로부터 수신할 것으로 예상되는 모의 페이로드를 테스트하십시오. 목적지 미리 보기 양식은 연동 사용자가 보는 화면과 일치합니다. 테스트 값으로 사용할 매개변수를 이 양식에 입력합니다. 이 양식에서 매핑된 속성과 필터를 구성할 수도 있습니다.

2. 테스트 모달을 열려면 연결 테스트를 클릭하십시오. 모든 필수 매개변수를 입력한 후 연결 테스트가 나타납니다. 이를 통해 페이로드를 사용자 정의할 수 있습니다. 테스트 이벤트 보내기를 클릭합니다. 지정한 엔드포인트의 전체 응답이 오른쪽에 표시됩니다.

3. 오류가 나타나면 매개변수 테이블을 확인하여 선언된 모든 매개변수가 해당 용도를 갖는지 확인하십시오.

   • 선언됨: 매개변수 생성 섹션에 선언된 모든 매개변수입니다.
   • 사용됨: URL, 헤더 및 이벤트 본문에 사용되는 모든 매개 변수입니다.

내부적으로 릴리즈

조직에서 테스트하려면 내부적으로 릴리스를 누릅니다. 이를 통해 조직 첫 사용 후 모든 사용자가 사용자가 정의한 연동을 사용할 수 있습니다. 변경 내용이 적용되려면 최대 5분이 걸립니다.

연동 제출

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