행동 코호트 수신하기

행동 코호트 동기화는 일련의 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를 사용하며 단일 API 요청으로 여러 사용자를 배치합니다. 기본적으로 배치에는 1,000명의 사용자가 포함되지만 배치 크기는 구성할 수 있습니다.
데이터 동기화를 일회성 동기화로 내보내거나 매시간 또는 매일 내보내도록 예약할 수 있습니다.
첫 번째 동기화는 전체 코호트에 대한 전체 동기화입니다. 후속 데이터 동기화에는 해당 코호트의 정의 안쪽이나 밖으로 이동한 사용자만 포함됩니다.
코호트 동기화 다음 기간동안 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"
}
'

이 내용이 도움이 되었나요?