---
title: "Customer.io 커넥터"
description: "Tajo를 통해 Customer.io의 사람, 이벤트, 캠페인, 워크플로 데이터를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/marketing/customerio/
markdown: https://tajo.io/kr/docs/connectors/marketing/customerio.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# Customer.io 커넥터

커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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 목록으로 복제
- **객체 데이터 동기화** - 비사람 객체 및 관계 데이터 동기화

## 사전 요구 사항

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

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로 인증합니다.

```bash
# 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": "user@example.com"}'
```

### App API (데이터 읽기)

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

```bash
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에 연결

```bash
tajo connectors install customerio \
  --site-id $CIO_SITE_ID \
  --track-api-key $CIO_TRACK_API_KEY \
  --app-api-key $CIO_APP_API_KEY
```

## 구성

### 기본 설정

```yaml
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 연락처 속성에 매핑합니다.

```yaml
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
```

### 이벤트 매핑

```yaml
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}` | 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 | 고객 활동 로그 가져오기 |

## 코드 예제

### 커넥터 초기화

```javascript
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로 동기화

```javascript
// 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
// }
```

### 이벤트 전달

```javascript
// 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');
});
```

### 세그먼트 내보내기

```javascript
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 호출 | 캠페인 데이터의 폴링 빈도 감소 |

### 디버그 모드

```yaml
connectors:
  customerio:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### 연결 테스트

```bash
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 서명으로 웹훅 페이로드 검증

## 관련 리소스

- [Braze 커넥터](https://tajo.io/kr/docs/connectors/marketing/braze)
- [Iterable 커넥터](https://tajo.io/kr/docs/connectors/marketing/iterable)
- [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)