micsapp Customer.io Known Pitfalls
Overview
Avoid common mistakes and anti-patterns when integrating with Customer.io across authentication, user identification, event tracking, data quality, and performance.
Prerequisites
- Active Customer.io integration
- Access to codebase with Customer.io calls
Quick Reference
| 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 |
Instructions
Step 1: Review Authentication
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.
Step 2: Audit User Identification
Ensure identify is called before track. Use immutable database IDs (not email). Include anonymous_id for merge when transitioning from anonymous to identified.
Step 3: Check Event Tracking
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.
Step 4: Validate Data Quality
Always include email attribute for email campaigns. Keep attribute types consistent. Never put PII in event names or segment names.
Step 5: Verify Delivery Handling
Handle bounces by suppressing users. Alert on spam complaints immediately. Always include unsubscribe links in email templates.
Step 6: Optimize Performance
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)
Error Handling
| 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 |
Resources
Next Steps
After reviewing pitfalls, proceed to customerio-reliability-patterns for fault tolerance.
Output
- Configuration files or code changes applied to the project
- Validation report confirming correct implementation
- Summary of changes made and their rationale
See optimization implementation details for output format specifications.
Examples
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.