Amplitude 커넥터
Tajo를 통해 Amplitude를 Brevo에 연결하여 프로덕트 애널리틱스 데이터를 마케팅 자동화에 활용하세요. 행동 기반 코호트, 사용자 속성, 프로덕트 이벤트를 동기화해 타깃팅된 캠페인을 구동하세요.
개요
| 속성 | 값 |
|---|---|
| 플랫폼 | Amplitude |
| 카테고리 | Analytics (Custom) |
| 설정 난이도 | 보통 |
| 공식 통합 | 아니오 |
| 동기화되는 데이터 | 이벤트, 사용자, 코호트, 속성 |
| 제공 스킬 | 6 |
주요 기능
- 이벤트 전달 - Amplitude의 track 이벤트를 마케팅 자동화 트리거로 Brevo에 전송합니다
- 코호트 동기화 - Amplitude 행동 기반 코호트를 Brevo 연락처 리스트로 내보냅니다
- 사용자 속성 동기화 - Amplitude 사용자 속성을 Brevo 연락처 속성에 매핑합니다
- 매출 추적 - 고객 생애 가치 분석을 위해 매출 이벤트를 동기화합니다
- 행동 기반 세분화 - Brevo 세그먼트에서 Amplitude 인게이지먼트 데이터를 사용합니다
- HTTP V2 API 통합 - Amplitude의 HTTP V2 수집 API와 직접 통합합니다
사전 준비 사항
시작하기 전에 다음 사항이 준비되어 있어야 합니다.
- 프로젝트가 생성된 Amplitude 계정
- Amplitude API Key와 Secret Key
- API 액세스가 활성화된 Brevo 계정
- API 자격 증명이 있는 Tajo 계정
인증
Amplitude API 키
Amplitude는 인증을 위해 API Key와 Secret Key 쌍을 사용합니다. API Key는 프로젝트를 식별하고, Secret Key는 서버 측 요청을 인증합니다.
# Find your keys in Amplitude:# Settings > Projects > [Your Project] > GeneralHTTP V2 API 인증
HTTP V2 API는 요청 본문에 API 키를 사용합니다.
curl -X POST https://api2.amplitude.com/2/httpapi \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_AMPLITUDE_API_KEY", "events": [...] }'설정
기본 설정
connectors: amplitude: enabled: true api_key: "your-amplitude-api-key" secret_key: "your-amplitude-secret-key" data_center: "US" # or "EU"
# Data sync options sync: events: true user_properties: true cohorts: true revenue: true
# Brevo list assignment lists: active_users: 10 power_users: 11 churning_users: 12이벤트 매핑
Amplitude 이벤트를 Brevo 자동화 트리거에 매핑합니다.
event_mapping: # Amplitude event -> Brevo event "Purchase": "order_completed" "Sign Up": "customer_created" "Add to Cart": "cart_updated" "Page View": "page_viewed" "Feature Click": "feature_used"
# Revenue events "Revenue": "revenue_event" "Subscription Started": "subscription_created"사용자 속성 매핑
Amplitude 사용자 속성을 Brevo 연락처 속성에 매핑합니다.
property_mapping: # Amplitude property -> Brevo attribute email: email first_name: FIRSTNAME last_name: LASTNAME phone: SMS plan_type: PLAN signup_date: SIGNUP_DATE total_purchases: ORDER_COUNT lifetime_revenue: LTV last_active: LAST_ACTIVE device_type: DEVICEAPI 엔드포인트
| Method | 엔드포인트 | 설명 |
|---|---|---|
POST | /2/httpapi | 이벤트 업로드 (HTTP V2 API) |
POST | /batch | 이벤트 대량 업로드 (Batch API) |
POST | /identify | 사용자 속성 설정 |
POST | /groupidentify | 그룹 속성 설정 |
GET | /2/export | 원본 이벤트 데이터 내보내기 |
GET | /2/usersearch | 사용자 검색 |
GET | /2/useractivity | 사용자 활동 타임라인 조회 |
POST | /api/3/cohort/export | 코호트 멤버 내보내기 |
GET | /api/3/chart/{chart_id}/query | 저장된 차트 데이터 조회 |
코드 예제
Amplitude 커넥터 초기화
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect Amplitude projectawait tajo.connectors.connect('amplitude', { apiKey: process.env.AMPLITUDE_API_KEY, secretKey: process.env.AMPLITUDE_SECRET_KEY, dataCenter: 'US'});HTTP V2 API로 이벤트 전송
// Send events to Amplitude (automatically forwarded to Brevo)const response = await fetch('https://api2.amplitude.com/2/httpapi', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ api_key: process.env.AMPLITUDE_API_KEY, events: [ { user_id: "user_123", event_type: "Purchase", event_properties: { revenue: 89.99, product_id: "SKU-001", product_name: "Widget Pro" }, user_properties: { $set: { plan_type: "premium" } }, time: Date.now() } ] })});
// Expected response: { "code": 200, "events_ingested": 1 }코호트를 Brevo 리스트로 동기화
// Export an Amplitude cohort and sync to Brevoconst cohort = await tajo.connectors.syncCohort('amplitude', { cohortId: 'abc123', targetList: 11, // Brevo list ID syncMode: 'mirror' // mirror, append, or remove});
console.log(cohort);// {// cohortName: "Power Users",// membersCount: 2450,// syncedToBrevo: 2450,// listId: 11// }요청 제한
| API | 제한 | 상세 |
|---|---|---|
| HTTP V2 API | 초당 1,000 이벤트 | 프로젝트당, 버스트 최대 초당 2,000 |
| Batch API | 배치당 1,000 이벤트 | 초당 최대 20 배치 |
| Identify API | 초당 1,000회 | 프로젝트당 |
| Export API | 시간당 360회 | 프로젝트당 |
| Cohort Export | 동시 내보내기 1회 | 코호트당 |
| Dashboard REST API | 시간당 360회 | 프로젝트당 |
이벤트 크기 제한
각 이벤트 페이로드는 1MB를 초과할 수 없습니다. HTTP V2 API는 요청당 최대 2,000개 이벤트를 수락하며 최대 본문 크기는 20MB입니다.
문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
이벤트가 invalid 상태 반환 | 필수 필드 누락 | 모든 이벤트에 user_id 또는 device_id가 설정되어 있는지 확인하세요 |
| 사용자 속성이 동기화되지 않음 | 잘못된 속성 연산자 | 설정에는 $set, 첫 번째 값에는 $setOnce를 사용하세요 |
| 코호트 내보내기가 비어 있음 | 코호트가 아직 계산 중 | 코호트 계산이 완료된 후 내보내기를 시도하세요 |
| 429 Too Many Requests | 요청 제한 초과 | 지수 백오프를 구현하고 batch API를 사용하세요 |
| 매출이 추적되지 않음 | 매출 필드 누락 | 이벤트 속성에 price, quantity, revenue를 포함하세요 |
| EU 데이터가 라우팅되지 않음 | 잘못된 데이터센터 | data_center: "EU"로 설정하고 api.eu.amplitude.com을 사용하세요 |
모범 사례
- HTTP V2 API 사용 - 더 나은 검증과 에러 응답을 위해 레거시 HTTP API보다 V2 API를 선호하세요
- 이벤트 배치 처리 - 최적의 처리량을 위해 최대 1,000개씩 이벤트를 배치로 전송하세요
- 이벤트에 사용자 속성 설정 - identify 호출을 줄이기 위해 track 이벤트에
user_properties를 포함하세요 - 세분화에 코호트 사용 - 복잡한 세분화 로직을 복제하는 대신 행동 기반 코호트를 동기화하세요
- 매출 이벤트를 올바르게 추적 - 정확한 매출 추적을 위해
revenue,price,productId필드를 사용하세요 - 수집 상태 모니터링 - 이벤트 검증 오류를 확인하기 위해 Amplitude의 Ingestion Debugger를 확인하세요
- 서버 측 추적 구현 - 안정적인 이벤트 전송을 위해 서버 측 SDK를 사용하세요
보안
- HTTPS 전용 - 모든 API 통신은 TLS 1.2+를 요구합니다
- API 키 순환 - Amplitude 설정에서 Secret Key를 주기적으로 교체하세요
- IP 허용 목록 - Enterprise 플랜에서 사용 가능
- SOC 2 Type II - Amplitude는 SOC 2 Type II 인증을 받았습니다
- GDPR/CCPA - 사용자 데이터 삭제 및 내보내기 요청 지원
- EU 데이터 레지던시 - EU 데이터센터 옵션 제공