Customer.io 커넥터

Customer.io 메시징 플랫폼을 Brevo에 연결하여 통합된 고객 데이터, 크로스 플랫폼 캠페인 조정, 통합된 참여 분석을 구현하십시오.

개요

속성
플랫폼Customer.io
카테고리Marketing
설정 복잡도보통
공식 통합아니오
동기화 데이터사람, 이벤트, 캠페인, 세그먼트
사용되는 APITrack API, App API, Pipelines API
인증Site ID + API Key / App API Key
Base URLtrack.customer.io, api.customer.io

기능

  • 사람 동기화 - Brevo 연락처와의 양방향 고객 프로필 동기화
  • 이벤트 전달 - 행동 이벤트를 추적하고 자동화 트리거를 위해 Brevo로 전달
  • 캠페인 분석 - 통합 보고를 위한 캠페인 성능 지표 동기화
  • 워크플로 데이터 - Brevo 연락처 속성에 Customer.io 워크플로 상태 미러링
  • 세그먼트 복제 - Customer.io 세그먼트를 Brevo 목록으로 복제
  • 객체 데이터 동기화 - 비사람 객체 및 관계 데이터 동기화

사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

  1. API 접근이 가능한 Customer.io 계정
  2. Site ID와 Track API Key (Settings > API Credentials에서 확인 가능)
  3. 캠페인 및 세그먼트 데이터 읽기용 App API 키
  4. API 접근이 가능한 Brevo 계정
  5. 활성 구독이 있는 Tajo 계정

인증

Customer.io는 서로 다른 인증 방법을 가진 두 개의 별도 API를 사용합니다.

Track API (행동 데이터)

사람, 이벤트, 장치 데이터 전송에 사용됩니다. Basic Auth를 통해 Site ID와 API Key로 인증합니다.

Terminal window
# 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" \
-d '{"email": "[email protected]"}'

App API (데이터 읽기)

캠페인, 세그먼트, 고객 데이터 가져오기에 사용됩니다. Bearer 토큰으로 인증합니다.

Terminal window
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에 연결

Terminal window
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_REQUEST

API 엔드포인트

Tajo는 다음 Customer.io API 엔드포인트와 통합됩니다.

엔드포인트메서드API목적
/api/v1/customers/{id}PUTTrack사람 생성 또는 업데이트
/api/v1/customers/{id}/eventsPOSTTrack사람 이벤트 추적
/api/v1/eventsPOSTTrack익명 이벤트 추적
/api/v2/entityPOSTTrack사람/객체 생성 또는 업데이트 (Pipelines)
/v1/campaignsGETApp캠페인 목록
/v1/campaigns/{id}/metricsGETApp캠페인 성능 지표
/v1/segmentsGETApp세그먼트 목록
/v1/segments/{id}/membershipGETApp세그먼트 멤버 가져오기
/v1/customers/{id}/attributesGETApp고객 속성 가져오기
/v1/customers/{id}/activitiesGETApp고객 활동 로그 가져오기

코드 예제

커넥터 초기화

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 API10 요청/초API 키당
Pipelines API100 요청/초대량 데이터에 권장
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

연결 테스트

Terminal window
tajo connectors test customerio
# ✓ Track API 연결 성공
# ✓ App API 연결 성공
# ✓ 사람 접근 가능
# ✓ 캠페인 읽기 가능
# ✓ 세그먼트 목록 가능

모범 사례

  1. 대량 데이터에 Pipelines API 사용 - 최신 Pipelines API는 대용량 수집에 최적화됨
  2. 보고 웹훅 설정 - Customer.io 이메일 이벤트를 Tajo로 실시간 전달
  3. 라이프사이클 단계 매핑 - Customer.io 세그먼트 멤버십을 Brevo 속성에 동기화
  4. 일관된 식별자 사용 - Customer.io와 Brevo에서 id 필드 일치
  5. 증분 동기화 - 전체 내보내기 대신 last_activity 타임스탬프 활용
  6. 웹훅 배달 모니터링 - 실패한 웹훅 배달에 대한 알림 설정

보안

  • Basic Auth - Track API는 Site ID와 API Key로 인증
  • Bearer 토큰 - App API는 OAuth 스타일 Bearer 토큰 사용
  • HTTPS 전용 - TLS 1.2+를 통해 암호화된 모든 API 통신
  • 지역별 데이터 센터 - GDPR 준수를 위한 EU 데이터 센터 옵션
  • 암호화된 저장 - Tajo에서 모든 자격 증명이 저장 시 암호화됨
  • 웹훅 서명 - HMAC 서명으로 웹훅 페이로드 검증

관련 리소스

Subscribe to updates

developer-docs

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

auto-detect
AI 어시스턴트

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