Customer.io 连接器

将您的 Customer.io 消息平台连接到 Brevo,实现统一的客户数据、跨平台营销活动协调以及整合的参与分析。

概览

属性
平台Customer.io
类别营销
设置复杂度中等
官方集成
同步数据人员、事件、营销活动、细分
使用的 APITrack API、App API、Pipelines API
认证方式网站 ID + API 密钥 / 应用 API 密钥
基础 URLtrack.customer.ioapi.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 密钥进行基本认证。

Terminal window
# 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": "[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" # 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_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

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

转发事件

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

导出细分

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 请求/秒推荐用于批量数据
批量端点每次请求 1,000 人最大负载 500KB

使用批量端点

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

故障排除

常见问题

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

调试模式

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

测试连接

Terminal window
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 负载

相关资源

Subscribe to updates

developer-docs

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

auto-detect
AI 助手

你好!关于文档有任何问题都可以问我。