Amplitude 커넥터

Tajo를 통해 Amplitude를 Brevo에 연결하여 프로덕트 애널리틱스 데이터를 마케팅 자동화에 활용하세요. 행동 기반 코호트, 사용자 속성, 프로덕트 이벤트를 동기화해 타깃팅된 캠페인을 구동하세요.

개요

속성
플랫폼Amplitude
카테고리Analytics (Custom)
설정 난이도보통
공식 통합아니오
동기화되는 데이터이벤트, 사용자, 코호트, 속성
제공 스킬6

주요 기능

  • 이벤트 전달 - Amplitude의 track 이벤트를 마케팅 자동화 트리거로 Brevo에 전송합니다
  • 코호트 동기화 - Amplitude 행동 기반 코호트를 Brevo 연락처 리스트로 내보냅니다
  • 사용자 속성 동기화 - Amplitude 사용자 속성을 Brevo 연락처 속성에 매핑합니다
  • 매출 추적 - 고객 생애 가치 분석을 위해 매출 이벤트를 동기화합니다
  • 행동 기반 세분화 - Brevo 세그먼트에서 Amplitude 인게이지먼트 데이터를 사용합니다
  • HTTP V2 API 통합 - Amplitude의 HTTP V2 수집 API와 직접 통합합니다

사전 준비 사항

시작하기 전에 다음 사항이 준비되어 있어야 합니다.

  1. 프로젝트가 생성된 Amplitude 계정
  2. Amplitude API Key와 Secret Key
  3. API 액세스가 활성화된 Brevo 계정
  4. API 자격 증명이 있는 Tajo 계정

인증

Amplitude API 키

Amplitude는 인증을 위해 API Key와 Secret Key 쌍을 사용합니다. API Key는 프로젝트를 식별하고, Secret Key는 서버 측 요청을 인증합니다.

Terminal window
# Find your keys in Amplitude:
# Settings > Projects > [Your Project] > General

HTTP V2 API 인증

HTTP V2 API는 요청 본문에 API 키를 사용합니다.

Terminal window
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: DEVICE

API 엔드포인트

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 project
await 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 Brevo
const 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을 사용하세요

모범 사례

  1. HTTP V2 API 사용 - 더 나은 검증과 에러 응답을 위해 레거시 HTTP API보다 V2 API를 선호하세요
  2. 이벤트 배치 처리 - 최적의 처리량을 위해 최대 1,000개씩 이벤트를 배치로 전송하세요
  3. 이벤트에 사용자 속성 설정 - identify 호출을 줄이기 위해 track 이벤트에 user_properties를 포함하세요
  4. 세분화에 코호트 사용 - 복잡한 세분화 로직을 복제하는 대신 행동 기반 코호트를 동기화하세요
  5. 매출 이벤트를 올바르게 추적 - 정확한 매출 추적을 위해 revenue, price, productId 필드를 사용하세요
  6. 수집 상태 모니터링 - 이벤트 검증 오류를 확인하기 위해 Amplitude의 Ingestion Debugger를 확인하세요
  7. 서버 측 추적 구현 - 안정적인 이벤트 전송을 위해 서버 측 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 데이터센터 옵션 제공

관련 리소스

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI 어시스턴트

안녕하세요! 문서에 대해 무엇이든 물어보세요.