Customer.io 连接器
将您的 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 列表
- 对象数据同步 - 同步非人员对象和关系数据
前提条件
开始之前,请确保您已具备:
- 具有 API 访问权限的 Customer.io 账户
- 您的网站 ID 和 Track API 密钥(在”设置 > API 凭据”中找到)
- 用于读取营销活动和细分数据的应用 API 密钥
- 具有 API 访问权限的 Brevo 账户
- 具有有效订阅的 Tajo 账户
认证
Customer.io 使用两个具有不同认证方式的独立 API:
Track API(行为数据)
用于发送人员、事件和设备数据。通过网站 ID 和 API 密钥进行基本认证。
# Basic Auth: Site ID as username, API Key as passwordcurl -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" # 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 联系人属性:
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事件映射
event_mapping: # Customer.io event -> Brevo event 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
// Incremental sync of Customer.io peopleawait 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// }转发事件
// Forward Customer.io reporting webhook events to Brevoapp.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 请求/秒 | 推荐用于批量数据 |
| 批量端点 | 每次请求 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 调用过多 | 降低营销活动数据的轮询频率 |
调试模式
connectors: customerio: debug: true log_level: verbose log_api_calls: true测试连接
tajo connectors test customerio# ✓ Track API connection successful# ✓ App API connection successful# ✓ People accessible# ✓ Campaigns readable# ✓ Segments listable最佳实践
- 批量数据使用 Pipelines API - 新版 Pipelines API 针对高容量摄入进行了优化
- 设置报告 Webhook - 实时将 Customer.io 邮件事件转发到 Tajo
- 映射生命周期阶段 - 将 Customer.io 细分会员资格同步到 Brevo 属性
- 使用一致的标识符 - 在 Customer.io 和 Brevo 中匹配
id字段 - 增量同步 - 避免完整导出;利用
last_activity时间戳 - 监控 Webhook 投递 - 为失败的 Webhook 投递设置警报
安全
- 基本认证 - Track API 使用网站 ID 和 API 密钥进行认证
- Bearer 令牌 - App API 使用类 OAuth Bearer 令牌
- 仅 HTTPS - 所有 API 通信通过 TLS 1.2+ 加密
- 区域数据中心 - 欧盟数据中心选项,符合 GDPR
- 加密存储 - 所有凭据在 Tajo 中静态加密
- Webhook 签名 - 使用 HMAC 签名验证 Webhook 负载