コホート同期連携を作成する

コホート同期連携を構築することで、Amplitudeの行動コホートをユーザーIDのリストまたはカスタムユーザープロパティとしてプラットフォームに送信するようAmplitude連携ポータルを設定し、その後その設定をAmplitudeの顧客が有効にする送信先タイルにパッケージ化します。送信先カタログにご使用のプラットフォーム用のコホート同期連携がまだない場合にのみ、新しい連携を構築してください。既存の場合は、それを複製する代わりにそれを使用してください。

このガイドでは、例としてリストベースの統合を使用しています。 プロパティベースのコホート同期連携を構築する場合、手順がいくつか異なります。

連携のセットアップ

Amplitudeが連携を検証した後に、Amplitudeの宛先ページに表示される連携タイルを設定します。また、リストベースのコホート連携とプロパティベースのコホート連携のどちらかを選択する必要があります。各連携タイプの詳細については、「受信行動コホート」を参照してください。

1. 連携ポータルページ（設定＞開発者ポータル）から、[新しい送信先を追加] をクリックします。
2. ［Select Connection Information］ ドロップダウンからターゲット接続を選択します。
3. リストベースとプロパティベースのどちらでコホート連携を構築するかを選択してください。
   • リストベースのコホート連携: リストベースのコホート連携は、ターゲットシステムがユーザー識別子のリストとしてコホートを表す場合に最適に機能します。最初の同期ではリスト作成 API を呼び出す必要があります。その後、追加 API と削除 API を呼び出すと、リストメンバーシップが最新の状態に保たれます。
   • プロパティベースのコホート連携: プロパティベースのコホート連携は、ブールフラグやタグなどのカスタムユーザープロパティとしてコホートメンバーシップを表すシステムで最も効果的です。Amplitudeは、コホートメンバーシップが変更されたときに更新APIを呼び出してユーザープロパティを更新します。 リスト作成APIを使用する必要はありませんが、カスタムユーザープロパティを手動で作成する必要がある場合があります。
4. Next をクリックして送信先を設定します。

連携名

連携名はカタログページに表示されます。名前は、コホート同期連携全体でグローバルに一意である必要があります。

コホート同期連携を設定する

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

• *[設定]*タブでは、ペイロードとAmplitudeから受け取る予定の内容を設定できます。
• *「連携のテスト」*タブには、連携、変数、およびペイロードをプレビューする [送信先設定] フォームなど、構成がまとめられています。このタブから連携機能をテストすることもできます。

次のいくつかのセクションでは、設定とテストのオプションについて説明します。

認証方法を設定する

Amplitudeと貴社との間のAPIコールをどのように認証するかを決定します。

カスタムヘッダーをクリックし、次のオプションから選択します。

• No authentication：このオプションは認証ヘッダーを必要としません。
• 基本認証:APIキーとAPIシークレット (オプション) を認証ヘッダーとして使用します。
• 認証ヘッダー:APIキーを使用して認証します。
• ベアラートークン: ベアラートークンを認証ヘッダーとして使用します。

カスタムフィールドを作成する

これらのフィールドは、API コールのペイロードで宣言された $variable を収集し、置き換えます。また、お客様が連携を実現するために使用するモーダルも構築しています。ここで追加したフィールドは、ユーザーが連携を設定するときに必須フィールドになります。

• フィールドの種類： フィールドの種類を指定します （文字列、単一選択、ボタングループなど）。
• ペイロードで使用されるフィールド変数名：デフォルトでは、これは認証の選択と一致します。 たとえば、認証方法としてベアラートークンを選択した場合、それはbearer_tokenとなります。
• 表示名： 連携のセットアップ モーダルでユーザーに表示される名前です。 デフォルトでは、これは認証の選択と一致します。 たとえば、認証方式としてベアラートークンを選択した場合、「ベアラートークン」という名前のプレースホルダ表示名が付きます。
• 新しいカスタムフィールドを追加: ペイロードに必要な別の識別子を追加する必要がある場合は、文字列、単一選択、ボタングループなどのカスタムフィールドを追加できます。

フィールドのマッピング

フィールドをマップして、Amplitudeフィールドがシステム内のフィールドにどのように接続されるかを指定します。 マッピングの値は、ペイロード内のitem_templateを置き換えます。

連携ポータルでマッピングフィールドを設定すると、連携のユーザーの送信先設定にマッピングセクションが表示されます。このセクションでは、ユーザーはAmplitudeユーザープロパティを選択して、送信先システムのフィールドにマップできます。この設定は、カスタムユーザーIDもサポートしています。

• マッピングフィールド表示名：Amplitudeはこれを「キー」、「識別子」または「ユーザーIDマッピング」に設定することを推奨しています。
• Amplitudeマッピングフィールド：Amplitude内のフィールド名です。例：user_id_field_amplitude。
• フィールドの種類： 「文字列」または「単一選択」のいずれかです。
• 表示名：これは完全にカスタマイズ可能なため、説明的な名前を使用してください。 たとえば、ユーザー ID や Email アドレスなどです。
• 新しいマッピングを追加： 必要に応じて、文字列、単一選択、ボタングループなどのマッピングを追加します。

Slugify Amplitudeコホート名

コホート名をスラッグ化することで、それらを標準化できます。このオプションは、お使いのシステムが特殊文字や非 ASCII 文字をサポートしていない場合に役立ちます。 スラッグ化では、Unicode特殊文字とスペースをASCII文字とハイフンに置き換えることで、コホート名をURLスラッグに変換します。この機能は、エンドポイント ペイロードに $amplitude_cohort_name が含まれている場合にのみ機能します。slugify ルールは次のとおりです。

• 元のコホート名を正規化形式KD(NFKD)に変換します。これは適合性分解です。
• アルファベット(a-z、A-Z)、数字(0-9)、およびアンダースコア(_)を除く文字をハイフンに置き換えます。
• スラッグは100文字以内に制限してください。

リスト作成エンドポイント

リストベースの連携を行うには、3つのAPIを呼び出す必要があります。最初のAPIはリスト作成エンドポイントです。コホートが初めて同期されると、AmplitudeはこのAPIを呼び出し、お客様のプラットフォーム上にリストを作成します。 Amplitudeは、アプリが listIDの固有識別子を含むレスポンスを送信することを期待しています。AmplitudeはそのレスポンスからのlistIDを保存し、リスト更新用のペイロードの一部としてこのIDを使用します。

• URLエンドポイント: https://api.yourapp.com/list などのエンドポイントを定義します。コールで使用するメソッドを選択します。
• 送信先に送信するAPIペイロード: このペイロードをニーズに合わせてカスタマイズしてください。
• レスポンス内のリストIDへのパス: 該当なし

リスト作成エンドポイントのエラー

すべてのエンドポイントにエラーステータスコードとエラーメッセージを追加することで、エンドユーザーがデバッグを行い、より迅速にヘルプを得ることができます。

［エラー分類］を展開し、［新しいエラーを追加］をクリックして、ステータスコードをさらに追加します。Amplitudeは、必要なだけ多くのステータスコードとサブエラーコードを含めることを推奨しています。 これらのコードとメッセージを使用すると、エンドユーザーのデバッグ作業が高速になります。

1. Amplitudeは、複数のエラーに対して同じステータスコードを使用する場合に、サブエラーコードを使用することを推奨しています。

ほとんどのパートナーが使用しているステータスコードの一般的な例を次に示します。

• 200: 成功
• 400：無効なリクエスト
• 401: 認証されていません (無効な api_key)
• 404：ユーザーIDが無効です
• 429: スロットリング/レート制限

Amplitudeは、コホート同期が失敗した場合に備えて、失敗理由（説明）とエラーメッセージを明確に示すことを推奨しています。明確なメッセージはエンドユーザーの体験を向上させ、サポートに関する問題を減らすのに役立ちます。

ユーザーのエンドポイントを追加する

Amplitudeは、コホートがAmplitudeからアプリに同期するたびにユーザー追加APIを呼び出します。 この同期は、1時間ごとまたは毎日実行できます。 このコールは、現在のコホートサイズと最後に成功した同期との差を計算します。

• URL エンドポイント：URL に $list_Id プレースホルダを含めることができますが、このプレースホルダは必須ではありません。代わりにリストIDをペイロードに配置するようにAPIを設計することもできます。例: https://your.domain/lists/$listId/add。
• 送信先に送信するAPIペイロード：このペイロードをカスタマイズし、ペイロードがバッチかどうかを定義します。$items変数は重要なキーです。_ペイロード内の$items変数を置き換える項目の配列_が、この変数を置き換えます。

$items変数は通常、コホート内のすべてのユーザーを識別します。たとえば、同期によって既存のコホートに20人の新しいユーザーが追加される場合があります。Batchオブジェクトには20人のユーザーのリストなどのコレクションが含まれており、Amplitudeはこれら20個のオブジェクトをエンドポイントに送信します。ペイロードは次のようになります。

json { "userIds": $items, "context": { "integration":{ "name": "Amplitude Cohort Sync", "version": "1.0.0" } } }

• 各 API 呼び出しの最大項目数 (バッチサイズ)：デフォルトは 10,000 ですが、これを指定することもできます。Amplitudeのレコメンデーションは、コホートバッチごとに1万人のユーザーを確保することです。
• ペイロード内の$items変数を置換する項目の配列: ペイロード内の$item変数を置換するオブジェクトの形式を指定します。 例："$user_id_field_amplitude"。

可能な限りレート制限を避けてください。 レート制限がある場合（例えば、毎秒90リクエスト数など）、ユーザードキュメントでそのことを明示してください。Amplitudeは4つのリクエストを並列に送信し、各リクエストには最大10,000人のユーザーが含まれています。

ユーザー追加エンドポイントのエラー

Amplitudeは、すべてのステータスコード、失敗理由、エラーメッセージ、およびサブエラーコードを再度作成するのではなく、リスト作成エンドポイントから同じエラーコードセットを使用することをお勧めします。 **[他のエンドポイントからエラーをコピー] **を選択し、エラーが設定されているエンドポイントを選択します。

ユーザー削除エンドポイント

Amplitudeは、コホートがAmplitudeからアプリに同期するたびにユーザー削除APIを呼び出します。 この同期は、1時間ごとまたは毎日実行できます。 このコールは、現在のコホートサイズと最後に成功した同期との差を計算します。

• URL エンドポイント：URL に $listId プレースホルダを含めることができますが、このプレースホルダは必須ではありません。代わりにリストIDをペイロードに配置するようにAPIを設計することもできます。例: https://your.domain/lists/$listId/remove。
• 送信先に送信するAPIペイロード：このペイロードをカスタマイズし、ペイロードがバッチかどうかを定義します。$items変数は重要なキーです。_ペイロード内の$items変数を置き換える項目の配列_が、この変数を置き換えます。

$items変数は通常、コホート内のすべてのユーザーを識別します。たとえば、同期を実行すると、既存のコホートから20人のユーザーが削除される可能性があります。Batchオブジェクトには20人のユーザーのリストなどのコレクションが含まれており、Amplitudeはこれら20個のオブジェクトをエンドポイントに送信します。ペイロードは次のようになります。

json { "userIds": $items, "context": { "integration":{ "name": "Amplitude Cohort Sync", "version": "1.0.0" } } }

• 各 API 呼び出しの最大項目数 (バッチサイズ)：デフォルトは 10,000 ですが、これを指定することもできます。Amplitudeのレコメンデーションは、コホートバッチごとに1万人のユーザーを確保することです。
• ペイロード内の$items変数を置換する項目の配列: ペイロード内の$item変数を置換するオブジェクトの形式を指定します。 例："$user_id_field_amplitude"。

ユーザー削除エンドポイントのエラー

Amplitudeは、すべてのステータスコード、失敗理由、エラーメッセージ、およびサブエラーコードを再度作成するのではなく、リスト作成エンドポイントから同じエラーコードセットを使用することをお勧めします。 **[他のエンドポイントからエラーをコピー] **を選択し、エラーが設定されているエンドポイントを選択します。

エンドポイントのプレビューとテスト

レビュー用に設定を送信する前に、Amplitudeから受信すると予想されるモックペイロードをテストしてください。 ［Testing］ タブで、次の手順に従って設定をプレビューおよびテストします。

「テスト」タブの「送信先設定」フォームは、貴社の連携を利用するユーザーが閲覧するものと一致します。このフォームは、ペイロードヘッダーで定義したパラメータを制御します。

ユーザーを生成するには、CSV をアップロードするか、[再生成] をクリックして設定に基づいてユーザーを生成します。 CSV には、addまたは removeのいずれかを含む「操作」列が必要です。リスト作成ペイロードで使用されるパラメータはすべて、CSV 内のすべての行で同じである必要があります。 CSV には、使用する各パラメータの列も含まれている必要があります。

次に、デフォルト設定のサンプルCSVを示します。

operation,user_id_field_amplitude,amp_cohort_name,amp_cohort_id
add,user123,Unified Cohort,unified_cohort_001
add,user456,Unified Cohort,unified_cohort_001
remove,user789,Unified Cohort,unified_cohort_001
add,john.doe@example.com,Unified Cohort,unified_cohort_001

パラメータテーブルを確認して、設定がすべての変数に対応していることを確認し、エラーを解決してください。宣言されたすべてのフィールドが空でないことを確認してください。

• 宣言済み: 「認証コール、カスタムフィールド、およびマッピングフィールド」セクションで宣言されているすべての変数。
• 使用済み: ユーザーリストエンドポイント、ユーザー追加エンドポイント、ユーザー削除エンドポイントで使用されるすべての変数。
• 事前定義済み: Amplitudeが値を置き換える事前定義済みの変数です。

ヘッダーを変更するには、［Configuration］タブと［Testing］タブの［送信先設定］フォームを使用します。

ヘッダーとペイロードを確認してください。 準備が整ったら、Test Endpointをクリックして、事前定義済みのエンドポイントにテストAPI呼び出しを送信します。デバッグ用の応答またはエラーが表示されます。

Test Endpointをクリックすると、成功の応答が表示されます。$list_idを取得します。Amplitudeは、「Add Users Endpoint（ユーザー追加エンドポイント）」に$list_idを使用します。

{listId: $list_id}は、リスト作成 API 呼び出しに対して期待される応答です。 構造を変更するには、リスト作成設定の_応答値で [リスト ID へのパス]_ を変更します。

取得した $list_idを使用して、ユーザー追加およびユーザー削除エンドポイントをテストしてください。

また、「テスト連携」セクションにある「テストエンドポイント」ボタンを使用してエンドツーエンドをテストすることもできます。このボタンを使用すると、必要なすべてのテストが自動的に実行されます。

社内向けリリース

組織内でテストするには、[Release Internally] をクリックします。 これにより、組織内の誰でも、あなたが定義した連携を使用できるようになります。連携はすぐに利用可能になります。

連携を提出する

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