# Customer.io 高级故障排除 ## 概述用于诊断复杂的 Customer.io 集成问题的高级调试技术。 ## 先决条件 * 访问 Customer.io 仪表板 * 应用程序日志访问 * 了解您的集成架构 ## 故障排除框架 ### 第 1 阶段：症状识别 1. 预期的行为是什么？ 2. 实际行为是什么？ 3. 这个问题是什么时候开始的？ 4. 有多少用户/消息受到影响？ 5. 是持续的还是间歇性的？ ## 说明 ### 第1步：API调试 // lib/debug-client.ts 从'@customerio/track'导入{TrackClient，RegionUS}；接口调试结果{ 成功：布尔值；延迟：数字；请求ID？：字符串；错误？：{ 代码：字符串；消息：字符串；详细信息？：任何； }; } 导出类 DebugCustomerIO { 私人客户端：TrackClient；构造函数（）{ this.client = 新 TrackClient( process.env.CUSTOMERIO_SITE_ID!, process.env.CUSTOMERIO_API_KEY！， { 地区：美国地区 } ）； } 异步调试识别（用户 ID：字符串，属性：记录<字符串，任意> ): Promise<调试结果> { const start = Date.now(); console.log('=== Customer.io 调试：识别 ==='); console.log('用户ID：', userId); console.log('属性：', JSON.stringify(attributes, null, 2)); 尝试{ 等待 this.client.identify(userId, 属性); 常量结果： DebugResult = { 成功：真实，延迟：Date.now() - 开始 }; console.log('结果：成功'); console.log('延迟：', result.latency, 'ms'); 返回结果； } catch（错误：任何）{ 常量结果： DebugResult = { 成功：假，延迟：Date.now() - 开始，错误：{ 代码：error.statusCode || “未知”，消息：错误消息，详细信息：error.response?.body } }; console.log('结果：失败'); console.log('错误：', JSON.stringify(result.error, null, 2)); 返回结果； } } 异步调试轨道（用户 ID：字符串，事件：字符串，数据？：记录<字符串，任意> ): Promise<调试结果> { const start = Date.now(); console.log('=== Customer.io 调试：跟踪 ==='); console.log('用户ID：', userId); console.log('事件：', 事件); console.log('数据：', JSON.stringify(data, null, 2)); 尝试{ 等待 this.client.track(userId, { 名称: 事件, 数据 }); 返回{ 成功：真实，延迟：Date.now() - 开始 }; } catch（错误：任何）{ 返回{ 成功：假，延迟：Date.now() - 开始，错误：{ 代码：error.statusCode || “未知”，消息：错误消息 } }; } } } ### 第 2 步：用户资料调查 // 脚本/调查-user.ts 接口用户调查{ 用户ID：字符串；简介：{ 存在：布尔值；属性：记录<字符串，任意>；段：字符串[]； }; 活动：{ 最后识别：日期；最后事件：日期； eventCount24h：数量；最近的事件：字符串[]； }; 交货：{ 发送的电子邮件：数量；已发送电子邮件：数量；已打开的电子邮件：数量；跳出次数：数量；投诉：数量；抑制：布尔值； }; 问题：字符串[]； } 异步函数调查用户（用户ID：字符串）：Promise { 常量调查：UserInvestigation = { 用户 ID, 配置文件: { 存在: false, 属性: {}, 段: [] }, 活动：{ 最后识别：新日期（0），最后事件：新日期（0），事件计数24小时：0，最近发生的事件：[] }, 交货：{ 已发送电子邮件：0, 电子邮件已发送: 0, 已打开电子邮件：0, 反弹：0，投诉：0, 抑制：假 }, 问题：[] }; // 1.检查用户是否存在尝试{ const 配置文件 = 等待 fetchUserProfile(userId); 调查.简介 = { 存在：真实，属性：配置文件.属性，分段：配置文件.分段 }; } 捕获（错误）{ Survey.issues.push('在 Customer.io 中找不到用户个人资料'); 返回调查； } // 2. 检查是否缺少必需的属性 if (!investigation.profile.attributes.email) { Survey.issues.push('用户缺少电子邮件属性 - 无法接收电子邮件'); } // 3. 检查抑制状态如果（调查.交付.抑制）{ Survey.issues.push('用户被抑制 - 不会发送任何消息'); } // 4. 检查退回/投诉历史记录如果（调查.delivery.bounces > 0）{ Survey.issues.push(`用户有 ${investigation.delivery.bounces} 次退回`); } 如果（调查.交付.投诉> 0）{ Survey.issues.push(`用户有 ${investigation.delivery.complaints} 条垃圾邮件投诉 - 高优先级`); } // 5. 检查最近的活动 const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000); if (investigation.activity.lastIdentify < oneDayAgo) { 调查.issues.push('用户个人资料在 24 小时以上未更新'); } 返回调查； } ### 第 3 步：营销活动调试 // 脚本/debug-campaign.ts 接口营销活动调试{ 活动 ID：数字；状态：'活动'| '暂停' | '草稿'; 触发器：{ 类型：字符串；条件：任何； }; 观众：{ 段ID？：数字；估计大小：数量； }; 最近发送：数组<{ 用户ID：字符串；时间戳：日期；状态：字符串； }>; 问题：字符串[]； } 异步函数 debugCampaign(campaignId: number): Promise { 常量调试：CampaignDebug = { 活动 ID, 状态：'草稿'，触发器：{ 类型：''，条件：{} }，观众：{预计大小：0}，最近发送：[]，问题：[] }; // 从 API 获取活动详细信息 // 分析触发条件 // 检查观众规模 // 查看最近的发送活动 // 需要检查的常见问题 if (debug.status !== '活动') { debug.issues.push('活动未激活'); } if (debug.audience.estimatedSize === 0) { debug.issues.push('没有用户匹配活动受众'); } 返回调试； } ### 步骤 4：Webhook 调试 // lib/webhook-debugger.ts 从“加密货币”导入加密货币；接口 WebhookDebugResult { 签名有效：布尔值；有效负载解析：布尔值；已处理事件：数量；错误：数组<{ 事件：字符串；错误：字符串； }>; 处理时间：数量； } 导出函数 debugWebhook( rawBody：字符串，签名：字符串，秘密：字符串 ): WebhookDebugResult { const start = Date.now(); 常量结果：WebhookDebugResult = { 签名有效：假，有效负载解析：假，已处理事件：0，错误：[]，处理时间: 0 }; // 1. 验证签名 const 预期签名 = 加密 .createHmac('sha256', 秘密) .更新(rawBody) .digest('十六进制'); result.signatureValid = crypto.timingSafeEqual( Buffer.from(签名 || ''), Buffer.from(expectedSignature) ）； if (!result.signatureValid) { console.log('预期签名：', ExpectedSignature); console.log('收到签名：', 签名); result.processingTime = Date.now() - 开始；返回结果； } // 2. 解析有效负载尝试{ const 负载 = JSON.parse(rawBody); 结果.payloadParsed = true; // 3. 处理事件 for (payload.events 的 const 事件 || []) { 尝试{ console.log('正在处理事件：', event.metric, event.event_id); 结果.eventsProcessed++; } catch（错误：任何）{ 结果.错误.push({ 事件：event.event_id，错误：错误消息 }); } } } catch（错误：任何）{ 结果.错误.push({ 事件：“解析”，错误：错误消息 }); } result.processingTime = Date.now() - 开始；返回结果； } ###第五步：网络调试 #!/bin/bash # 脚本/debug-network.sh echo "=== Customer.io 网络诊断 === # 1.DNS解析 echo -e "\n1.DNS解析:" 挖掘 track.customer.io +short # 2. TCP 连接 echo -e "\n2. TCP 连接性:" nc -zv track.customer.io 443 2>&1 # 3.TLS 握手 echo -e "\n3. TLS 证书:" 回声| openssl s_client -connect track.customer.io:443 2>/dev/null | openssl s_client -connect track.customer.io:443 2>/dev/null | openssl x509 -noout -日期 # 4. API 响应时间 echo -e "\n4. API 延迟:" curl -o /dev/null -s -w "连接: %{time_connect}s\nTTFB: %{time_starttransfer}s\n总计: %{time_total}s\n" \ -X POST“https://track.customer.io/api/v1/customers/test”\ -u "$CUSTOMERIO_SITE_ID:$CUSTOMERIO_API_KEY" \ -H“内容类型：application/json”\ -d '{"email":"test@test.com"}' # 5. 检查速率限制 echo -e "\n5. 速率限制检查:" 对于 {1..5} 中的 i；做卷曲 -s -o /dev/null -w "%{http_code}\n" \ -X POST“https://track.customer.io/api/v1/customers/test-$i”\ -u "$CUSTOMERIO_SITE_ID:$CUSTOMERIO_API_KEY" \ -H“内容类型：application/json”\ -d '{"email":"test@test.com"}' 完成 ### 第 6 步：事件响应操作手册 ## Customer.io 事件响应操作手册 ### P1：API 完全中断 1.检查https://status.customer.io/ 2. 验证凭据尚未过期 3.直接用curl测试 4. 启用断路器（如果可用） 5. 将事件排队以进行重试 6. 通知利益相关者 ### P2：高错误率（>5%） 1. 按类型检查错误分布 2. 确定受影响的运营 3.查看最近的代码部署 4. 检查速率限制 5. 如果是自己造成的，就缩小规模 ### P3：交付问题 1. 检查退回率/投诉率 2. 审查禁止名单 3. 验证发件人信誉 4. 检查活动配置 5. 审查分部条件 ### P4：Webhook 失败 1. 验证 webhook 秘密 2. 检查端点可用性 3. 检查负载格式 4. 检查重复事件 5. 验证幂等性处理 ## 诊断命令 # 检查API健康状况卷曲-s“https://status.customer.io/api/v2/status.json”| jq '.状态' # 测试认证卷曲-u“$CIO_SITE_ID：$CIO_API_KEY”“https://track.customer.io/api/v1/accounts” # 检查用户是否存在卷曲-u“$CIO_SITE_ID：$CIO_API_KEY”“https://track.customer.io/api/v1/customers/USER_ID” ## 错误处理问题 |解决方案 ---|--- 用户未收到|检查抑制、分段未跟踪的事件 |首先验证用户身份高延迟 |检查网络，启用池化 ## 资源 * [Customer.io 状态]() * [问题排查指南]() ## 后续步骤故障排除后，继续执行“customerio-reliability-patterns”以获得弹性。

Customerio 高级故障排除

包含技能