Customer.io 커넥터
Customer.io 메시징 플랫폼을 Brevo에 연결하여 통합된 고객 데이터, 크로스 플랫폼 캠페인 조정, 통합된 참여 분석을 구현하십시오.
개요
| 속성 | 값 |
|---|---|
| 플랫폼 | Customer.io |
| 카테고리 | Marketing |
| 설정 복잡도 | 보통 |
| 공식 통합 | 아니오 |
| 동기화 데이터 | 사람, 이벤트, 캠페인, 세그먼트 |
| 사용되는 API | Track API, App API, Pipelines API |
| 인증 | Site ID + API Key / App API Key |
| Base URL | track.customer.io, api.customer.io |
기능
- 사람 동기화 - Brevo 연락처와의 양방향 고객 프로필 동기화
- 이벤트 전달 - 행동 이벤트를 추적하고 자동화 트리거를 위해 Brevo로 전달
- 캠페인 분석 - 통합 보고를 위한 캠페인 성능 지표 동기화
- 워크플로 데이터 - Brevo 연락처 속성에 Customer.io 워크플로 상태 미러링
- 세그먼트 복제 - Customer.io 세그먼트를 Brevo 목록으로 복제
- 객체 데이터 동기화 - 비사람 객체 및 관계 데이터 동기화
사전 요구 사항
시작하기 전에 다음이 준비되어 있는지 확인하십시오.
- API 접근이 가능한 Customer.io 계정
- Site ID와 Track API Key (Settings > API Credentials에서 확인 가능)
- 캠페인 및 세그먼트 데이터 읽기용 App API 키
- API 접근이 가능한 Brevo 계정
- 활성 구독이 있는 Tajo 계정
인증
Customer.io는 서로 다른 인증 방법을 가진 두 개의 별도 API를 사용합니다.
Track API (행동 데이터)
사람, 이벤트, 장치 데이터 전송에 사용됩니다. Basic Auth를 통해 Site ID와 API Key로 인증합니다.
# Basic Auth: Site ID는 사용자 이름, API Key는 비밀번호curl -X POST https://track.customer.io/api/v1/customers/user123 \ -u "$SITE_ID:$API_KEY" \ -H "Content-Type: application/json" \App API (데이터 읽기)
캠페인, 세그먼트, 고객 데이터 가져오기에 사용됩니다. Bearer 토큰으로 인증합니다.
curl -X GET https://api.customer.io/v1/campaigns \ -H "Authorization: Bearer $APP_API_KEY"API 키 분리
Track API 키와 App API 키는 서로 다른 자격 증명입니다. Track API 키는 데이터 쓰기에 사용되며, App API 키는 데이터 읽기에 사용됩니다. 전체 Tajo 통합을 위해서는 둘 다 필요합니다.
Tajo에 연결
tajo connectors install customerio \ --site-id $CIO_SITE_ID \ --track-api-key $CIO_TRACK_API_KEY \ --app-api-key $CIO_APP_API_KEY구성
기본 설정
connectors: customerio: enabled: true region: "us" # 또는 EU 데이터 센터의 경우 "eu"
sync: people: true events: true campaigns: true segments: true objects: false
lists: all_contacts: 12 active_subscribers: 13 churned: 14필드 매핑
Customer.io 사람 속성을 Brevo 연락처 속성에 매핑합니다.
field_mapping: # 표준 필드 id: CIO_ID email: email first_name: FIRSTNAME last_name: LASTNAME phone: SMS
# 참여 지표 created_at: SIGNUP_DATE last_activity: LAST_ACTIVE plan: PLAN_NAME
# 맞춤 속성 company: COMPANY role: JOB_TITLE mrr: MONTHLY_REVENUE lifecycle_stage: LIFECYCLE_STAGE이벤트 매핑
event_mapping: # Customer.io 이벤트 -> Brevo 이벤트 purchase_completed: ORDER_PLACED subscription_started: SUBSCRIPTION_START feature_activated: FEATURE_USED support_ticket_opened: SUPPORT_REQUESTAPI 엔드포인트
Tajo는 다음 Customer.io API 엔드포인트와 통합됩니다.
| 엔드포인트 | 메서드 | API | 목적 |
|---|---|---|---|
/api/v1/customers/{id} | PUT | Track | 사람 생성 또는 업데이트 |
/api/v1/customers/{id}/events | POST | Track | 사람 이벤트 추적 |
/api/v1/events | POST | Track | 익명 이벤트 추적 |
/api/v2/entity | POST | Track | 사람/객체 생성 또는 업데이트 (Pipelines) |
/v1/campaigns | GET | App | 캠페인 목록 |
/v1/campaigns/{id}/metrics | GET | App | 캠페인 성능 지표 |
/v1/segments | GET | App | 세그먼트 목록 |
/v1/segments/{id}/membership | GET | App | 세그먼트 멤버 가져오기 |
/v1/customers/{id}/attributes | GET | App | 고객 속성 가져오기 |
/v1/customers/{id}/activities | GET | App | 고객 활동 로그 가져오기 |
코드 예제
커넥터 초기화
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
await tajo.connectors.connect('customerio', { siteId: process.env.CIO_SITE_ID, trackApiKey: process.env.CIO_TRACK_API_KEY, appApiKey: process.env.CIO_APP_API_KEY, region: 'us'});사람을 Brevo로 동기화
// Customer.io 사람의 증분 동기화await tajo.connectors.sync('customerio', { type: 'incremental', resources: ['people'], since: '2024-01-01', batchSize: 100});
const status = await tajo.connectors.status('customerio');console.log(status);// {// connected: true,// lastSync: '2024-03-15T14:20:00Z',// peopleCount: 32500,// campaignsTracked: 18,// eventsProcessed: 87000// }이벤트 전달
// Customer.io 보고 웹훅 이벤트를 Brevo로 전달app.post('/webhooks/customerio', async (req, res) => { const events = req.body;
for (const event of events) { await tajo.connectors.handleEvent('customerio', { type: event.metric, payload: { customerId: event.data.customer_id, campaignId: event.data.campaign_id, timestamp: event.timestamp } }); }
res.status(200).send('OK');});세그먼트 내보내기
const result = await tajo.connectors.exportSegment('customerio', { segmentId: 42, targetList: 13, includeAttributes: ['email', 'first_name', 'last_name', 'plan']});
console.log(`Exported ${result.count} people to Brevo list 13`);속도 제한
Customer.io는 API당 서로 다른 속도 제한을 적용합니다.
| API | 속도 제한 | 참고 |
|---|---|---|
| Track API | 약 100 요청/초 | 워크스페이스당 |
| App API | 10 요청/초 | API 키당 |
| Pipelines API | 100 요청/초 | 대량 데이터에 권장 |
| Batch 엔드포인트 | 요청당 1,000명 | 최대 페이로드 500KB |
Batch 엔드포인트 사용
대규모 동기화의 경우, Tajo는 Customer.io 배치 엔드포인트를 사용하여 요청당 최대 1,000명을 전송하므로 API 호출 볼륨이 크게 줄어듭니다.
문제 해결
일반적인 문제
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 401 Unauthorized | 잘못된 Site ID 또는 API 키 | Customer.io Settings > API에서 자격 증명 확인 |
| 사람이 동기화되지 않음 | 식별자 누락 | 각 사람에 id 또는 email이 있는지 확인 |
| 이벤트가 추적되지 않음 | 잘못된 API 키 유형 | 이벤트에는 App API 키가 아닌 Track API 키 사용 |
| EU 데이터에 접근할 수 없음 | 잘못된 지역 구성 | EU 워크스페이스의 경우 지역을 eu로 설정 |
| 속도 제한 오류 | 너무 많은 App API 호출 | 캠페인 데이터의 폴링 빈도 감소 |
디버그 모드
connectors: customerio: debug: true log_level: verbose log_api_calls: true연결 테스트
tajo connectors test customerio# ✓ Track API 연결 성공# ✓ App API 연결 성공# ✓ 사람 접근 가능# ✓ 캠페인 읽기 가능# ✓ 세그먼트 목록 가능모범 사례
- 대량 데이터에 Pipelines API 사용 - 최신 Pipelines API는 대용량 수집에 최적화됨
- 보고 웹훅 설정 - Customer.io 이메일 이벤트를 Tajo로 실시간 전달
- 라이프사이클 단계 매핑 - Customer.io 세그먼트 멤버십을 Brevo 속성에 동기화
- 일관된 식별자 사용 - Customer.io와 Brevo에서
id필드 일치 - 증분 동기화 - 전체 내보내기 대신
last_activity타임스탬프 활용 - 웹훅 배달 모니터링 - 실패한 웹훅 배달에 대한 알림 설정
보안
- Basic Auth - Track API는 Site ID와 API Key로 인증
- Bearer 토큰 - App API는 OAuth 스타일 Bearer 토큰 사용
- HTTPS 전용 - TLS 1.2+를 통해 암호화된 모든 API 통신
- 지역별 데이터 센터 - GDPR 준수를 위한 EU 데이터 센터 옵션
- 암호화된 저장 - Tajo에서 모든 자격 증명이 저장 시 암호화됨
- 웹훅 서명 - HMAC 서명으로 웹훅 페이로드 검증