ストリーミング変換

ストリーミング変換は、カスタムイベント、派生プロパティ、変換済みイベント、変換済みプロパティなど、Amplitudeタクソノミーから変換済みデータをイベントストリーミングの宛先に送信するため、ダウンストリームのツールは未加工イベントの代わりにクリーンアップされ、強化されたデータを受け取ります。イベントストリーミングを設定するときに、任意の変換を選択します。変換をストリーミングするには、まずAmplitudeデータで変換を定義する必要があります。カスタムイベント、派生プロパティ、その他の変換タイプを作成するには、「変換」を参照してください。

セットアップ

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 は、エンドツーエンドの p95 レイテンシを 60 秒にすることを目標としています。 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）。完全なデータ構造については、イベント形式およびユーザー (Identify) 形式を参照してください。

ドットと括弧の表記法

プロパティ名が有効な識別子である場合はドット表記を使用し、名前にスペースやその他の特殊文字が含まれている場合はブラケット表記を使用します：

${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 では、マージされたプロパティやカートのプロパティに基づいてネストされたプロパティを選択できますが、実際には機能しません。

よくある質問