스트리밍 변환

스트리밍 변환은 사용자 지정 이벤트, 파생 속성, 변환된 이벤트 및 변환된 속성을 포함하여 Amplitude 택소노미에서 변환된 데이터를 이벤트 스트리밍 대상으로 전송하므로 다운스트림 도구는 원시 이벤트 대신 정리되고 강화된 데이터를 수신합니다. 이벤트 스트리밍을 구성할 때 트랜스포메이션을 선택합니다. Amplitude Data를 스트리밍하려면 먼저 트랜스포메이션을 정의해야 합니다. 사용자 정의 이벤트, 파생 속성 및 기타 트랜스포메이션 유형을 생성하려면 트랜스포메이션을 참조하십시오.

설정

1. Amplitude 데이터에서 카탈로그를 클릭하고 대상 탭을 선택합니다.
2. 이벤트 스트리밍 섹션에서 전체 스트리밍 목적지 타일을 클릭합니다.
3. 동기화 이름을 입력한 다음 동기화 생성을 클릭합니다.
4. 상태를 비활성화됨에서 활성화됨으로 전환합니다.
5. 대상의 서버 암호 키를 붙여넣습니다.
6. 이벤트 전송을 토글하여 이벤트 스트리밍을 활성화합니다.
7. 이벤트 선택 및 필터링에서 전송할 이벤트를 선택합니다. 다운스트림 목적지에 필요한 이벤트만 선택합니다. 드롭다운에는 사용자의 택소노미에서 변환된 전체 이벤트가 포함됩니다.
8. (선택 사항) 추가 속성 선택에서 포함할 전체 이벤트 속성(변환된 이벤트 속성 포함)을 선택합니다. 기본적으로 Amplitude는 사용자가 명시적으로 선택하지 않는 한 전체 추가 속성을 전송하지 않습니다.
9. (선택 사항) 추가 사용자 속성 선택에서 포함할 전체 사용자 속성을 선택합니다. 기본적으로 Amplitude는 사용자가 명시적으로 선택하지 않는 한 전체 추가 사용자 속성을 전송하지 않습니다.
10. 구성에 만족하면 저장을 클릭합니다.

활용 사례 예제

이름이 바뀐 이벤트를 AppsFlyer로 스트리밍

AppsFlyer는 어트리뷰션을 위해 고유한 이벤트 이름을 요구하며 이벤트 속성을 지원하지 않습니다. 이전에는 백엔드에서 사용자 지정 이벤트를 생성한 후 Amplitude로 다시 전송해야 했습니다. 이제 Amplitude 데이터를 사용하여 이벤트를 AppsFlyer로 스트리밍하기 전에 이벤트의 이름을 변경할 수 있으므로 중복 수집이 줄어듭니다.

파생 속성을 Braze로 스트리밍

캠페인의 효과를 높이기 위해 Amplitude에서 파생 속성을 Braze로 스트리밍할 수 있습니다. 동기화 필터에서 파생 속성을 선택하고 추가 속성을 구성할 때 이를 포함시킵니다. 이를 통해 Amplitude의 풍부한 이벤트 데이터를 사용하여 더 정교하게 타겟팅된 캠페인을 진행할 수 있습니다.

고려 사항

Amplitude에서 변형을 스트리밍할 때 다음 사항에 유의하십시오.

• Amplitude는 선택한 이벤트와 사용자 속성을 이벤트와 함께 전송합니다.
• Amplitude는 60초의 엔드투엔드 p95 지연 시간을 목표로 합니다. Amplitude는 이벤트의 95%를 60초 첫 사용 후 스트리밍합니다. Amplitude는 이 목표를 달성하기 위해 내부 프로세스, 모니터링 및 경고를 갖추고 있습니다.

트랜스포메이션 페이로드 구조

스트리밍 페이로드는 중첩된 JSON 필드로 변환을 포함합니다. 사용자 지정 FTL(FreeMarker 템플릿 언어) 템플릿을 사용하거나 목적지가 데이터를 수신하는 방법을 구성할 때 이 구조를 이해하는 것이 필수적입니다.

선발 요건

스트리밍 페이로드에 포함하려면 동기화 구성에서 변환을 명시적으로 선택해야 합니다. 다음 위치에서 변형을 선택할 수 있습니다.

• 이벤트 선택 및 필터링: 예를 들어 파생 속성이 가 아닌 이벤트를 필터링합니다null.
• 추가 속성 선택: 변환된 특정 속성을 포함하려면
• 목적지에 속성 매핑: 속성을 목적지의 스키마에 매핑할 때(해당되는 경우).

스트리밍 페이로드에는 사용자가 명시적으로 선택한 변환만 포함됩니다.

JSON 구조

페이로드에는 중첩된 JSON 객체로서 변환이 포함됩니다. 최상위 필드 이름은 트랜스포메이션 유형에 따라 다릅니다.

이러한 오브젝트 내의 필드 이름은 Amplitude UI에 표시된 트랜스포메이션 이름과 일치합니다.

페이로드 예제

sample_derived_property_key1라는 파생 속성을 선택하면 스트리밍 페이로드는 다음과 같습니다.

{
  "event_type": "Button Clicked",
  "user_id": "12345",
  "derived_properties": {
    "sample_derived_property_key1": "whatever_value"
  }
}

사용자 지정 FTL을 사용하여 변환 사용

목적지에서 사용자 지정 FTL 템플릿을 사용하는 경우 이러한 패턴을 사용하여 트랜스포메이션 데이터에 액세스할 수 있습니다.

예제 1: FtlUtils를 사용하여 파생 속성을 직렬화함

<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
  "version": "derived_properties_sample_ftl1",
  "derived_properties": ${UtilClass.toJson(input.derived_properties)}
}

예 2: 파생 속성에 대해 수동으로 반복

<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
  "version": "derived_properties_sample_ftl2",
  "derived_properties": {
    <#list input.derived_properties?keys as key>
      "${key}": "${input.derived_properties[key]}"<#sep>,</#sep>
    </#list>
  }
}

FreeMarker(FTL)를 사용하여 페이로드 사용자 지정

사용자 지정 페이로드 편집기를 노출하는 이벤트 스트리밍 목적지는 Apache FreeMarker(FTL)를 사용하여 Amplitude 이벤트를 목적지가 기대하는 JSON 본문으로 변환합니다. 커넥터 빌더의 편집기는 아래 필드와 도우미에 대한 자동 완성, 마우스 오버 문서 및 인라인 유효성 검사를 제공합니다. FreeMarker 언어 자체에 대해서는 템플릿 만들기 가이드를 참조하십시오.

입력 객체

input는 Amplitude가 전달하는 이벤트(또는 사용자)입니다. 값을 출력하려면 점 표기법을 사용하여 해당 필드에 액세스하십시오${ }.

"${input.user_id}"
"${input.event_type}"
"${input.event_time}"

일반적으로 사용 가능한 필드에는 event_type, user_id, device_id, time, event_time, session_id, platform, event_properties, user_properties, group_properties, 및 groups가 포함되며, 선택한 변형(derived_properties, lookup_properties)도 포함됩니다. 전체 형태에 대해서는 이벤트 형식 및 사용자(식별) 형식을 참조하십시오.

점 및 괄호 표기법

속성 이름이 유효한 식별자인 경우 점 표기법을 사용하고, 이름에 스페이스나 기타 특수 문자가 포함되어 있을 경우 괄호 표기법을 사용합니다.

${input.event_properties.plan}
${input.event_properties["Plan Type"]}

누락된 필드 처리

필드는 보장되지 않으므로 값이 누락되지 않도록 주의하십시오.

• ?? 값이 존재하는지 테스트합니다<#if input.user_id??>…</#if>.
• ! 값이 누락된 경우 기본값을 제공합니다. ${input.user_properties.email!} (빈 문자열) 또는 ${input.revenue!0}.

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

유용한 내장 기능

FreeMarker 내장 기능(?name)은 값을 변환합니다. JSON 페이로드에 대한 일반적인 사항:

속성에 대한 반복 작업

항목 사이에만 <#list>쉼표를 넣으려면 ?keys및 <#sep>와 함께 사용하십시오.

"user_properties": {
  <#list input.user_properties?keys as key>
    "${key}": ${UtilClass.toJsonString(input.user_properties[key])}<#sep>,</#sep>
  </#list>
}

도우미 메서드(FtlUtils)

Amplitude는 값을 직렬화하기 위한 도우미 메서드와 기타 일반적인 변환을 제공하므로 로직을 직접 작성할 필요가 없습니다. 템플릿 맨 위에서 도우미를 한 번 할당한 다음 해당 메서드를 호출하십시오.

<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
  "user_properties": ${UtilClass.toJson(input.user_properties)}
}

예제

각 예제는 Amplitude가 전달하는 입력 이벤트, 사용자가 작성한 템플릿, 그리고 Amplitude가 목적지로 전송하는 결과 정보를 보여줍니다.

간단함: 필드 이름을 바꾸고 선택하기

몇 가지 입력 필드를 목적지에서 기대하는 모양으로 매핑하십시오.

입력 이벤트:

{
  "event_type": "Song Played",
  "user_id": "user-123",
  "event_time": "2024-01-15T09:30:00.000",
  "event_properties": {
    "song_id": "abc-987"
  }
}

템플릿:

{
  "external_id": "${input.user_id}",
  "name": "${input.event_type}",
  "song": "${input.event_properties.song_id}"
}

결과:

{
  "external_id": "user-123",
  "name": "Song Played",
  "song": "abc-987"
}

복잡성: 가드, 대괄호 표기법 및 반복

??를 사용하여 선택적 필드를 보호하고, 대괄호 표기법으로 이름에 공백이 있는 속성을 읽고, ?c를 사용하여 숫자를 포맷하며, <#list>를 사용하여 반복함으로써 모든 사용자 속성을 직렬화하고, 숫자와 부울은 원시 값으로, 기타 모든 것은 toJsonString을 통해 방출합니다.

입력 이벤트:

{
  "event_type": "Purchase Completed",
  "user_id": "user-123",
  "revenue": 12.5,
  "event_properties": {
    "Item Name": "Pro Plan"
  },
  "user_properties": {
    "email": "alex@example.com",
    "plan": "pro",
    "age": 30
  }
}

템플릿:

<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
  "event": "${input.event_type}",
  <#if input.user_id??>
  "user_id": "${input.user_id}",
  </#if>
  "item": "${input.event_properties["Item Name"]}",
  "revenue": ${input.revenue?c},
  "traits": {
    <#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><#sep>,</#sep>
    </#list>
  }
}

결과:

{
  "event": "Purchase Completed",
  "user_id": "user-123",
  "item": "Pro Plan",
  "revenue": 12.5,
  "traits": {
    "email": "alex@example.com",
    "plan": "pro",
    "age": 30
  }
}

지원되는 사용자 지정 이벤트

Amplitude는 특정 기준을 충족하는 사용자 지정 이벤트를 스트리밍할 수 있도록 지원합니다. Amplitude 택소노미에서 사용자 지정 이벤트를 생성할 때 다음과 같은 조건이 있는 경우 이벤트 스트리밍을 위해 해당 이벤트를 선택할 수 있습니다.

• 지원되는 속성: 사용자 속성 및 이벤트 속성만 해당합니다.
• 지원되는 연산자: is, is not, contains, 및 does not contain.

다른 속성 유형이나 연산자를 사용하는 사용자 지정 이벤트는 이벤트 스트리밍 구성에서 선택할 수 없습니다.

제한 사항

Amplitude의 스트리밍 변환에는 몇 가지 제한이 있습니다.

• 사용자 정의 이벤트 또는 파생 속성의 이름을 바꿀 때는 이를 참조하는 기존 동기화 구성을 업데이트하십시오. 데이터 동기화가 제대로 작동하려면 현재 이벤트 및 속성 이름이 필요합니다. 트랜스포메이션의 기본 정의를 변경해도 동기화에는 영향을 주지 않습니다. 이름 변경 사항만 동기화 업데이트가 필요합니다.
• 조회 속성: Amplitude에 대한 액세스를 요청하여 조회 속성을 스트리밍할 수 있습니다. 조회 속성은 CSV 파일 업로드를 사용하여 기존 이벤트 또는 사용자 속성을 새 속성에 매핑하며, 쿼리 시 이미 수집된 이벤트를 보강할 수 있습니다.
  • 행이 1000개를 넘는 조회 속성 파일은 스트리밍 설정에 표시되지 않습니다.
  • 조회 속성 파일을 저장한 후 스트리밍 시스템에 데이터를 입력하는 데 최대 1시간이 걸릴 수 있습니다.
• 채널 분류기: 채널 분류기를 스트리밍하려면 Amplitude에 대한 액세스를 요청하십시오. 채널은 쿼리 다음 기간동안 실시간으로 적용되는 파생 속성과 같은 역할을 합니다. 마케터들은 주로 채널을 사용하여 UTM 및 추천자 데이터를 기반으로 유입 채널을 정의합니다. 기본적으로 Amplitude가 조직에 대해 이 기능을 이미 활성화하지 않은 경우 동기화 구성에서 채널 속성(이벤트 필터 또는 추가 속성)을 선택할 수 없습니다.
• 변환을 데이터 웨어하우스 대상을 제외한 모든 스트리밍 대상으로 스트리밍할 수 있습니다.
• 스트리밍 설정은 다음 트랜스포메이션 유형을 지원하지 않습니다.
  • 지원되는 사용자 지정 이벤트 섹션의 기준을 충족하지 않는 사용자 지정 이벤트입니다.
  • 그룹 속성
  • 카트 속성.
  • 중첩된 속성(예: 다른 파생 속성에 의존하는 파생 속성) 예외: UI에서는 병합된 속성이나 카트 속성을 기반으로 중첩된 속성을 선택할 수 있지만 실제로는 작동하지 않습니다.

자주 묻는 질문