Customer.io Known Pitfalls 是一份针对 Customer.io 集成实践的反模式与坑点清单，用于在审查集成、新人入门、审计现有 Customer.io 使用时识别并规避常见错误。
前置条件
资料列出了使用该清单前应具备的条件：明确的工作区、同意/数据分类、事件 schema 以及部署负责人；以及一个合成测试配置文件和脱敏的诊断流程，默认情况下不要用生产收件人做排查。
使用方式
资料给出的操作流程为：在修改事件、campaign、segment 或集成设置之前，先确认适用的坑点；在开发/预发环境验证 schema、身份、同意状态、环境和幂等性；做一处可回滚的修正，并用合成数据验证效果后再发布；将反复出现的失败记录到经过审查的 runbook/契约中，而不是依赖临时重试。
输出方面，针对某个具体的投递、数据、同意或集成坑点，产出文档化的预防或修正方案。
错误处理规则：环境或收件人范围错误时，停止发送、修正配置，并按事件流程评估/通知；事件 schema 意外变更时，隔离无效事件，并在重放前对契约做版本管理；同意状态不确定时，在验证之前不要发消息或重放。
12 个常见坑点
-
API 密钥类型错误：Track API 使用 Basic Auth（Site ID + Track Key），App API 使用 Bearer Auth（App Key），两者不可互换。用 Track key 调事务性消息接口会返回 401。
-
毫秒时间戳：Customer.io 期望 Unix 秒。JavaScript 的 Date.now() 返回毫秒，虽不报错但会被当作秒解释，导致日期变成数千年后，使用日期比较的 segment 会静默失效。应使用 Math.floor(Date.now() / 1000)。
-
track 早于 identify：对不存在的用户调用 track 可能被静默丢弃，应先 identify() 再 track()。
-
用邮箱作为用户 ID：identify() 的第一个参数是永久用户 ID。若使用邮箱，用户改邮箱后会产生重复 profile，应改用不可变的数据库主键，邮箱只作为属性。
-
缺少 email 属性：没有 email 属性的用户 profile 虽存在，但无法接收任何邮件 campaign 或事务性消息。
-
动态事件名：如 viewed_${productId} 会产生成百上千个唯一事件名，污染事件目录并导致无法创建 campaign 触发器。应使用固定事件名，把变化部分放进 data 属性。
-
阻塞请求链路：Customer.io 追踪属于非关键分析，不应给每个用户请求增加 200ms+ 延迟，应使用 fire-and-forget 加 .catch() 处理。
-
不处理退信：继续向退信地址发送会损害发件人声誉，最终导致所有邮件进入垃圾箱。应通过 webhook 处理退信并调用 suppress。
-
每个请求新建客户端：每次 new TrackClient() 都会创建新连接，单例模式复用 TCP 连接可降低 50-80% 延迟。
-
事件名不一致：事件名区分大小写，混用 PascalCase、kebab-case、空格会导致触发器只匹配一种变体，应统一使用 snake_case。
-
无限流：Customer.io 限流约 100 req/sec，批量导入时全速调用会触发 429 错误，甚至导致 API key 被临时封禁。应使用 Bottleneck 或 p-queue 之类的限流工具。
-
事件名中包含 PII：事件名会被索引和缓存，其中的 PII 无法为 GDPR 合规而删除，PII 应只放在事件 data 属性中。
快速对照表
资料附有 12 条坑点与对应修复的速查表，便于在代码审查时逐项核对。
集成审计脚本
资料提供了一段可用于代码库的 grep 审计命令，检查是否存在未除以 1000 的 Date.now()、函数内 new TrackClient、动态事件名、路由中的阻塞式 await 调用等常见问题。
适用场景与限制
该清单适合作为代码审查清单和开发者入门参考，也可用于审计已有集成。资料同时给出后续步骤：审查完坑点后，可使用 customerio-reliability-patterns 处理容错相关问题。资料未提供具体价格、平台支持范围或效果承诺等信息。