行動コホートの受信

行動コホート同期は、一連の REST API 呼び出しを通じてコホートメンバーシップデータをパートナープラットフォームに送信します。リストベースの連携では、Amplitudeはコホートメンバーシップのリストを作成および更新します。プロパティベースの連携では、Amplitudeはユーザープロパティまたはトレイトを設定します。

行動コホートとは、音楽アプリで曲をダウンロードしたり、商品をカートに追加したりしたユーザーなど、同様の行動をとるユーザーのグループです。また、特定のアクションを起こさないユーザーとして行動コホートを定義することもできます。たとえば、アプリをダウンロードしたがサブスクリプションへのサインアップを完了しなかったユーザーなどです。

REST APIリクエストを認証する

REST API は基本認証を使用します。パートナーは、api_keyをユーザー名と空のパスワードとして送信する必要があります。

bash

curl -u api_key https://[ INSERT URL ]
Setting traits/properties on user:
JSON_HEADERS = {
       'Content-Type': 'application/json',
  }
Auth: ($api_key, '')

行動コホートに関する考慮事項

AmplitudeはバルクAPIを使用し、1つのAPIリクエストで複数のユーザーをバッチ処理します。デフォルトでは、バッチには1000人のユーザーが割り当てられますが、バッチサイズは設定可能です。
同期を1回限りの同期としてエクスポートするようにスケジュールすることも、1時間ごとまたは毎日エクスポートするようにスケジュールすることもできます。
最初の同期は、コホート全体の完全な同期です。その後の同期には、コホートの定義内または外に移動したユーザーのみが含まれます。
コホート同期中、Amplitudeはユーザーが属する各コホートに対して個別のリクエストを送信します。
明示的なレート制限はありません。デフォルトでは、Amplitudeはダウンストリームプラットフォームへのリクエストを送信するために4つのスレッドを使用します。
Amplitudeで作成できるコホート数に制限はありません。
リクエストが失敗した場合、Amplitudeは指数関数的なバックオフを使用して8回再試行します。再試行の遅延は1秒から始まり、徐々に長くなって、最後の再試行では2分を超えます。

リストベースのコホート連携

リストベースのコホート連携は、ターゲットシステムがコホートをユーザー識別子のリストとして表している場合に最適に機能します。最初の同期時にリスト作成APIを呼び出す必要があります。その後、add APIとremove APIを呼び出して、リストメンバーシップを最新の状態に保ちます。

リスト作成

bash

POST https://your.domain/lists
{
    'name': [Amplitude] {$cohort_name}: {$cohort_id},
    'context': {
        'integration': {
            'name': 'Amplitude Cohort Sync',
            'version': '1.0.0'
        }
    }
}

ユーザーをリストに追加する

bash

POST https://your.domain/lists/$listId/add
{
    'userIds':[$userId, $userId, ...]
    'context': {
        'integration': {
            'name': 'Amplitude Cohort Sync',
            'version': '1.0.0'
        }
    }
}

リストからユーザーを削除する

bash

POST https://your.domain/lists/$listId/remove
{
    'userIds':[$userId, $userId, ...]
    'context': {
        'integration': {
            'name': 'Amplitude Cohort Sync',
            'version': '1.0.0'
        }
    }
}

プロパティベースのコホート連携

プロパティベースのコホート連携は、コホートのメンバーシップをブール値のフラグやタグなど、カスタムユーザープロパティとして表現するシステムで最も効果を発揮します。コホートのメンバーシップが変更されると、AmplitudeはupdateAPIを呼び出してユーザープロパティを更新します。ここではリスト作成APIは必要ありませんが、カスタムユーザープロパティを手動で作成する必要がある場合があります。

単一の更新

bash

POST https://your.domain/lists/$listId/remove
{
    'type': 'identify',
    'traits': {
        '[Amplitude] {$cohort_name}: {$cohort_id}': True / False
    },
    'userId': '$user_id',
    'context': {
        'integration': {
            'name': 'Amplitude Cohort Sync',
            'version': '1.0.0'
        }
    }
}

バッチ更新

bash

POST https://your.domain/lists/$listId/remove
{
    'batch': [{
        'type': 'identify',
        'traits': {
            '[Amplitude] {$cohort_name}: {$cohort_id}': True / False
        },
        'userId': '$user_id',
        'context': {
            'integration': {
                'name': 'Amplitude Cohort Sync',
                'version': '1.0.0'
            }
        }
    }, {
        'type': 'identify',
        'traits': {
            '[Amplitude] {$cohort_name}: {$cohort_id}': True / False
        },
        'userId': '$user_id',
        'context': {
            'integration': {
                'name': 'Amplitude Cohort Sync',
                'version': '1.0.0'
            }
        }
    }]
}

レスポンス

200：成功
400：無効なリクエスト
401：認証失敗（不正api_key）
404：ユーザーIDが無効です
429：スロットリング/レート制限

Amplitudeは、ユーザーがコホートの一部になったときに、コホートメンバーのプロパティをtrueに設定します。ユーザーがコホートを離れると、Amplitudeはプロパティをfalseに設定します。

行動コホート連携のテスト

テストを行うために、AmplitudeはAmplitudeから受信予定のモックペイロードを作成することをお勧めします。コホート統合の場合、典型的なペイロード構造は次のとおりです。

bash

curl --location --request POST 'https://app.staging-01.TEST_COMPANY_NAME.com/api/v1/integration/amplitude/cohort \
--header 'api_key: TEST_API_KEY' \
--header 'app_id: TEST_APP_ID' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "traits": {
    "cohort name:123": true
  },
  "type": "identify",
  "userId": "test.user@email.com"
}
'

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