---
title: "Customer.io 连接器"
description: "完整的 Customer.io 集成指南，通过 Tajo 将人员、事件、营销活动和工作流数据与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/marketing/customerio/
markdown: https://tajo.io/zh-cn/docs/connectors/marketing/customerio.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 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 |
| **类别** | 营销 |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | 人员、事件、营销活动、细分 |
| **使用的 API** | Track API、App API、Pipelines API |
| **认证方式** | 网站 ID + API 密钥 / 应用 API 密钥 |
| **基础 URL** | `track.customer.io`、`api.customer.io` |

## 功能

- **人员同步** - 与 Brevo 联系人的双向客户档案同步
- **事件转发** - 跟踪行为事件并转发到 Brevo 触发自动化
- **营销活动分析** - 同步营销活动绩效指标，用于统一报告
- **工作流数据** - 在 Brevo 联系人属性中镜像 Customer.io 工作流状态
- **细分复制** - 将 Customer.io 细分复制为 Brevo 列表
- **对象数据同步** - 同步非人员对象和关系数据

## 前提条件

开始之前，请确保您已具备：

1. 具有 API 访问权限的 Customer.io 账户
2. 您的网站 ID 和 Track API 密钥（在”设置 > API 凭据”中找到）
3. 用于读取营销活动和细分数据的应用 API 密钥
4. 具有 API 访问权限的 Brevo 账户
5. 具有有效订阅的 Tajo 账户

## 认证

Customer.io 使用两个具有不同认证方式的独立 API：

### Track API（行为数据）

用于发送人员、事件和设备数据。通过网站 ID 和 API 密钥进行基本认证。

```bash
# Basic Auth: Site ID as username, API Key as password
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"  # or "eu" for EU data center

    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:
  # Standard fields
  id: CIO_ID
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Engagement metrics
  created_at: SIGNUP_DATE
  last_activity: LAST_ACTIVE
  plan: PLAN_NAME

  # Custom attributes
  company: COMPANY
  role: JOB_TITLE
  mrr: MONTHLY_REVENUE
  lifecycle_stage: LIFECYCLE_STAGE
```

### 事件映射

```yaml
event_mapping:
  # Customer.io event -> Brevo event
  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
// Incremental sync of Customer.io people
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
// Forward Customer.io reporting webhook events to 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 请求/秒 | 推荐用于批量数据 |
| **批量端点** | 每次请求 1,000 人 | 最大负载 500KB |

使用批量端点

对于大型同步，Tajo 使用 Customer.io 批量端点每次请求发送最多 1,000 人，显著减少 API 调用量。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | 网站 ID 或 API 密钥无效 | 在 Customer.io 设置 > API 中验证凭据 |
| 人员未同步 | 缺少标识符 | 确保每个人员都有 `id` 或 `email` |
| 事件未跟踪 | API 密钥类型错误 | 事件使用 Track API 密钥，而非 App API 密钥 |
| 欧盟数据不可访问 | 区域配置错误 | 欧盟工作区将 region 设置为 `eu` |
| 速率限制错误 | App API 调用过多 | 降低营销活动数据的轮询频率 |

### 调试模式

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

### 测试连接

```bash
tajo connectors test customerio
# ✓ Track API connection successful
# ✓ App API connection successful
# ✓ People accessible
# ✓ Campaigns readable
# ✓ Segments listable
```

## 最佳实践

1. **批量数据使用 Pipelines API** - 新版 Pipelines API 针对高容量摄入进行了优化
2. **设置报告 Webhook** - 实时将 Customer.io 邮件事件转发到 Tajo
3. **映射生命周期阶段** - 将 Customer.io 细分会员资格同步到 Brevo 属性
4. **使用一致的标识符** - 在 Customer.io 和 Brevo 中匹配 `id` 字段
5. **增量同步** - 避免完整导出；利用 `last_activity` 时间戳
6. **监控 Webhook 投递** - 为失败的 Webhook 投递设置警报

## 安全

- **基本认证** - Track API 使用网站 ID 和 API 密钥进行认证
- **Bearer 令牌** - App API 使用类 OAuth Bearer 令牌
- **仅 HTTPS** - 所有 API 通信通过 TLS 1.2+ 加密
- **区域数据中心** - 欧盟数据中心选项，符合 GDPR
- **加密存储** - 所有凭据在 Tajo 中静态加密
- **Webhook 签名** - 使用 HMAC 签名验证 Webhook 负载

## 相关资源

- [Braze 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/braze)
- [Iterable 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/iterable)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)