このページでは

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

コホートWebhook

コホート Webhook は、コホートの更新を Webhook エンドポイントに送信します。 エンドポイントの要件に基づいてカスタムデータの拡張、フィルタリング、または集約に使用できます。 変換されたデータをマーケティングオートメーションプラットフォームやその他のシステムに統合することで、最新のコホートインサイトを使用してパーソナライズされたキャンペーンを強化できます。

考慮事項

  • この連携を使用したい各Amplitudeプロジェクトで有効にしてください。
  • コホート Webhookを使用するには、Amplitudeの有料プランが必要です。
  • コホートWebhookは、追加または削除のバッチを送信先に送信します。送信先は各バッチを1～2秒以内に処理する必要があるため（ネットワーク遅延を含めて）、Amplitudeは再試行制限内に200のOKレスポンスを受信します。送信先が時間内に応答しない場合、コールはタイムアウトして再試行されます。このため、重複したペイロードが発生する可能性があります。
  • Amplitudeは、Postmanなどのツールを使用して送信先エンドポイントのレイテンシをテストし、レスポンスが期待される時間枠内に収まることを確認することを推奨します。
  • 処理に時間がかかる場合は、ただちに 200 OK を返し、ペイロードを非同期に処理する非同期 API パターンを使用してください（たとえば、インメモリキューを使用します）。

連携を設定する

  1. AmplitudeからWebhookへのストリーミングを設定するには、以下の情報を収集してください：

    • Webhook URL：Amplitudeがイベントとユーザーを送信するために使用する送信先URLです。
    • ヘッダー情報：Webhookリクエストに対して最大5つの追加ヘッダーを設定できます。

  2. 新しい送信先を作成します。

    1. Amplitudeデータで、**[カタログ]をクリックし、[宛先]**タブを選択します。
    2. [コホート] セクションで、[Webhook] をクリックします。

  3. Webhook の URL エンドポイントを入力します。 例：https://mycompany.com/webhook。Amplitudeはイベントやユーザーを転送するための単一のIPアドレスを持っていないため、URLは任意のAmplitudeホストからのペイロードを受け入れる必要があります。

  4. すべての Webhook 同期には、2 つのプリセットヘッダーが含まれています。

    • Content-Type: application/json
    • User-Agent: Amplitude/Webhook/1.0

    プリセットされたヘッダーのあとに 5 つのヘッダーを定義できます。 新しいヘッダーを作成するには：

    1. 左側のテキストボックスにヘッダー名を入力します。
    2. 右側のテキストボックスにヘッダー値を入力します。
    3. 制限に達していない場合は、新しいヘッダー行が表示されます。

  5. Webhookで受け取るペイロードを定義します。次のことが可能です。

    1. Amplitudeコホート形式に従ったデフォルトのAmplitudeペイロードを送信します。
    2. Apache FreeMarker テンプレートを使用してペイロードをカスタマイズします。 詳細については、FreeMarkerテンプレート言語を参照してください。

  6. [保存] をクリックして設定を完了します。

送信先へのコホート同期を確立する

  1. Amplitudeで、エクスポートしたいコホートを開きます。
  2. [同期] をクリックし、[Webhook] を選択します。
  3. 定義済みのWebhook送信先を選択します。
  4. （オプション）ユーザーと一緒に持ち運ぶユーザープロパティを最大50個選択できます。Amplitudeは選択したプロパティをユーザーペイロードに追加し、FreeMarkerテンプレートでアクセスできるようにします。
  5. 同期のケイデンスを選択します。
  6. 同期をクリックして同期を開始します。

FreeMarkerテンプレート言語

詳しい情報については、テンプレート作成に関するFreeMarkerガイドを参照してください。

ユーザー ID のみのコホート更新を送信するためのテンプレートの例

{
   "cohort_name": "${input.cohort_name}",
   "cohort_id": "${input.cohort_id}",
   "in_cohort": ${input.in_cohort?c},
   "computed_time": "${input.computed_time}",
   "message_id": "${input.message_id}",
   "users": [
   <#list input.users as user>
   {
      "user_id": "${user.user_id}"
   }<#sep>,
   </#list>
   ]
}

ユーザープロパティのコホートの更新情報をユーザーに送信するためのテンプレートの例

{
    "cohort_name": "${input.cohort_name}",
    "cohort_id": "${input.cohort_id}",
    "in_cohort": ${input.in_cohort?c},
    "computed_time": "${input.computed_time}",
     "message_id": "${input.message_id}",
    "users": [
     <#list input.users as user>
     {
         "user_id": "${user.user_id}",
         "user_properties": {
            <#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><#if key_has_next>,</#if>
            </#list>
        }
      }<#sep>,
     </#list>
]
}

ユーザーごとにコホート情報を送信するためのテンプレートの例

一部の Webhook の宛先では、ユーザーのリストを一括で必要とします。 次の例では、ユーザーがそのコホートに属しているかどうかを示す単一の論理値プロパティとしてコホート名とコホート ID を設定しています。

[ < #list input.users.iterator() as user > {
	'user_id': '${user.user_id}',
	'amplitude_${input.cohort_name}_${input.cohort_id}': $ {
		input.in_cohort
	}
} < #if user_has_next > , < /#if></#list > ]

テンプレート参照

  • FreeMarkerは、${ ... }構文を波括弧内の式の値に置き換えます。
  • inputは、イベントをオブジェクトとして参照する予約済み変数です。inputオブジェクトは、サンプルペイロードと同じ形式に従います。
  • inputオブジェクトの形式は次のとおりです。
    • cohort_name 文字列です。コホートの表示名。
    • cohort_id 文字列です。コホートの一意の識別子です。
    • in_cohortブール値です。このユーザーバッチがコホートに入るか退去するかを示します。
    • computed_time 文字列です。Amplitudeがこの更新を計算した時間は、Unixエポック時間を秒単位で表します（例："1692206763"）。
    • message_id 文字列です。この更新メッセージの一意の識別子。 この値を使用して、再試行時に重複除外を実行します。
    • users JSONオブジェクトのリスト。ユーザーのペイロード。
      • user_id 文字列です。ユーザーのAmplitudeuser_idです。
      • user_properties JSONオブジェクト。このコホート同期中にこのユーザーに対して選択されたユーザープロパティ。

これは役に立ちましたか？