Avoid common mistakes and anti-patterns when integrating with Customer.io across authentication, user identification, event tracking, data quality, and performance.
| Pitfall | Fix |
|---|---|
| Wrong API key | Track API for tracking, App API for transactional |
| Milliseconds | Use Math.floor(Date.now() / 1000) |
| Track before identify | Always identify first |
| Changing user IDs | Use immutable database IDs |
| No email attribute | Include email for email campaigns |
| Dynamic event names | Use properties instead |
| Blocking requests | Fire-and-forget pattern |
| No bounce handling | Suppress on bounce |
| No rate limiting | Use Bottleneck or similar |
| New client per request | Reuse client singleton |
| Inconsistent event names | Use consistent snake_case |
| PII in event names | Use event data properties |
Verify you use Track API key for identify/track and App API key for transactional/reporting. Check timestamps use Unix seconds (not milliseconds). Remove any hardcoded credentials.
Ensure identify is called before track. Use immutable database IDs (not email). Include anonymous_id for merge when transitioning from anonymous to identified.
Standardize on snake_case event names. Use event data properties for variations instead of dynamic event names. Use fire-and-forget for non-critical tracking.
Always include email attribute for email campaigns. Keep attribute types consistent. Never put PII in event names or segment names.
Handle bounces by suppressing users. Alert on spam complaints immediately. Always include unsubscribe links in email templates.
Reuse the TrackClient singleton. Implement rate limiting with Bottleneck. Never block request paths waiting for analytics calls.
For detailed code examples of each pitfall and the anti-pattern audit script, load the reference guide:
Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)
| Issue | Solution |
|---|---|
| Integration audit fails | Review each category systematically |
| Existing bad data | Run cleanup scripts, re-identify users |
| Performance degradation | Check for per-request client creation |
After reviewing pitfalls, proceed to customerio-reliability-patterns for fault tolerance.
See optimization implementation details for output format specifications.
Basic usage: Apply customerio known pitfalls to a standard project setup with default configuration options.
Advanced scenario: Customize customerio known pitfalls for production environments with multiple constraints and team-specific requirements.
