イベントストリーミング連携を作成する

イベントストリーミング連携は、イベントが発生したときにリアルタイムでAmplitudeから送信先に転送します。プラットフォームがAmplitudeのイベントデータを受信する必要がある場合に、このタイプの連携を構築してください。代わりにイベントデータをAmplitudeに送信するには、イベント取り込み連携を構築してください。

イベントストリーミングに関する考慮事項

サポートされる機能

• イベント転送：イベント転送は、Amplitude Trackコールを送信先に送信します。Amplitudeは、生イベントとマージまたは変換されたイベントの両方を転送します。 Amplitude は event_nameおよび created_atを送信先にも送信します。
• イベントフィルタリング：Amplitudeにはきめ細かなフィルタリングオプションがあり、ユーザーは選択したイベントタイプとプロパティ条件に基づいて送信するイベントを選択できます。
• イベント選択プロパティ転送：ユーザーは、転送されるイベントのペイロードに含めるイベント、ユーザー、またはグループのプロパティを選択できます。
• 通常のユーザー識別転送（ユーザーの作成と更新）：送信先に対して識別転送機能を有効にします。この機能により、送信先は Identify API で作成されたユーザーとそのプロパティをリアルタイムで送信できます。詳細については、Identify のドキュメントを参照してください。
• ユーザープロパティのマッピング：ユーザーはAmplitudeユーザープロパティを選択して、送信先のフィールドにマッピングできます。この設定は、カスタムユーザーIDもサポートしています。

イベントストリーミングの制限事項

• ユーザー選択プロパティ転送：Amplitudeは許可リストに基づくイベントからの特定のイベント、グループ、ユーザープロパティの転送をサポートしていません。
• 配列またはオブジェクトタイプのプロパティを転送する: 配列またはオブジェクトタイプのプロパティを転送することはできません。たとえば、都市の配列であるcities という名前のプロパティを転送することはできません。
• 変更ベースのユーザー識別転送：イベントの取り込み中にユーザープロパティが変更された場合、Amplitudeは識別イベントを自動的に生成して転送しません。
• プロパティ値トランスフォーメーション: 元のイベントタイプがわからない場合、プロパティ値または型を別の値または型に変換することはできません。
• 選択的なプロパティ転送タイプ：Amplitudeは、ユーザーが転送したすべてのカスタムプロパティを文字列として送信します。
• OAuth認証：AmplitudeはOAuthをサポートしていないため、パートナーはAPIキーを生成する必要があります。
• イベントカテゴリ名：Amplitudeはイベントカテゴリ名を送信しません。

イベントストリーミングエンドポイントを準備する

1. Freemarker：Amplitudeがイベントを送信するために使用するテンプレートエンジンであるFreemarkerについてよく理解してください。
2. レート制限: レート制限をできるだけ高く設定して、スロットリングを最小限に抑えます。 たとえば、AmplitudeはBrazeが通信するレート制限（イベントトラッキング用に1分間に5万件のリクエスト）を尊重します。Amplitudeには指数関数的なバックオフ機能を備えた再試行メカニズムがあり、4時間にわたって9回試行できます。 このプロセスにより、一時的なスロットリングが解決されます。
3. イベント制限: イベントサイズの制限は、顧客のユースケースに合わせて十分な柔軟性を確保してください。

4. 認証方法：AmplitudeはOAuthをサポートしていないため、パートナーはAPIキーを生成する必要があります。
5. エンドポイントの柔軟性: Amplitudeは特定の形式でオブジェクトのリストを生成します。 エンドポイントがこのペイロード構造を処理することを確認してください。 ペイロードの例については、次のセクションを参照してください。

連携のセットアップ

Amplitudeの「Destinations」ページに表示される連携タイルを設定します。

1. 連携ポータルページ（設定＞開発者ポータル）から、[新しい送信先を追加] をクリックします。
2. **[送信先タイプの選択] の下で、[イベントストリーミング] **を選択します。

セットアップモーダルの例

Amplitudeで完成したセットアップモーダルの例を表示するには、Amplitudeの_データデスティネーション_に移動し、イベントストリーミングとマークされている任意の連携を追加してください。

イベントストリーミング連携を構成する

設定ページには2つのセクションがあります。

• _[設定]_タブでは、ペイロードとAmplitudeから受け取る予定の内容を設定できます。
• _Testing_タブには、連携のセットアップ モーダル 画面、パラメータ、ペイロードなど、設定内容がまとめられています。このタブでは、カスタムペイロードを使用して設定をテストすることもできます。

連携名

連携名はカタログページに表示されます。名前は、イベントストリーミング統合全体でグローバルに一意である必要があります。

パラメータの作成

このセクションでは、URL、ヘッダー、およびイベント本文で使用できるパラメータを定義できます。

• パラメータ表示名：これは完全にカスタマイズ可能なため、説明的なものを使用してください。この値はAmplitudeの表示名です。 たとえば、「REST APIエンドポイントとREST APIキー」などです。
• パラメータ名：ペイロード、URL、またはヘッダーは、対応するパラメータにこのIDを使用します。

ユーザープロパティマッピングをカスタマイズ

このセクションでは、ユーザーが選択したAmplitudeユーザープロパティを入力できるペイロード内のフィールドを定義できます。 たとえば、ほとんどの宛先では、ここにあるフィールドをユーザー識別子として使用し、必須として設定します。

• ［送信先プロパティ名］：これはフィールド名と表示名の両方として機能します。
• 必須チェックボックス：このオプションをオンにすると、ユーザーはこのフィールドを設定するまでイベントを送信先に転送できません。

イベントペイロードをカスタマイズ

［イベント ペイロードのカスタマイズ］ セクションを使用して、ペイロードに含まれるものをカスタマイズできます。

• 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、ヘッダー、およびイベント本文で使用されるすべてのパラメータ。

社内向けリリース

組織内でテストするには、[Release Internally] をクリックします。 これにより、組織内の誰でも、あなたが定義した連携を使用できるようになります。変更が有効になるまで最大 5 分かかります。

連携を提出する

テストが完了したら、[送信] をクリックして連携をAmplitudeチームに送信してください。審査プロセスには約1週間かかります。 Amplitudeがお客様の連携を承認すると、Amplitudeはお客様にメールで通知し、お客様の連携タイルがAmplitudeの「宛先」セクションに表示されます。