Packages and Configuration Options (SDK) for Customer.io

Overview

If you’re using Customer.io in a D2C app, SDK package choices and configuration details aren’t “technical housekeeping”—they directly determine whether cart recovery, browse follow-up, and winback audiences are accurate. If you want a second set of eyes on your tracking plan before you scale spend and automations, book a strategy call and we’ll pressure-test identity stitching and event coverage like an operator would.

In most retention programs, the biggest performance swings come from two things: (1) whether the SDK reliably identifies the same person across sessions/devices, and (2) whether events are sent with the right properties at the right time. “Packages” and “options” are where those two either get locked in—or quietly break.

How It Works

Customer.io’s SDKs are typically modular: you install a core package (collects device/app context and handles the basic client) and then add optional packages depending on what you need (push handling, in-app messaging, deep links, etc.). The configuration options you choose determine how the SDK behaves in the real world—especially around identity, event batching, and which automatic data gets collected.

• Core SDK initialization: you initialize the SDK with your site/workspace credentials and environment settings. This is also where you set defaults like logging level and (in some SDKs) region/endpoint behavior.
• Identity stitching via identify(): the SDK starts life as “unknown” (or anonymous) until you call identify with a stable identifier (email, customer_id, etc.). This is the pivot point for retention accuracy—get it wrong and you’ll split one shopper into multiple profiles.
• Event tracking via track(): you send behavioral events (e.g., Product Viewed, Add to Cart, Checkout Started, Order Completed) with properties. Customer.io uses these events to trigger campaigns, build segments, and measure conversions.
• Optional packages: push and in-app packages typically add device token registration, notification click handling, and in-app display logic. These packages matter for cart recovery and reactivation because they control whether you can reliably reach known users on-device and attribute conversions properly.
• Data flow reality: the SDK queues events on-device and sends them to Customer.io over the network. Options like batching/retry/logging can change how resilient this is under spotty connectivity—common on mobile.

Step-by-Step Setup

The goal here isn’t just “SDK installed.” It’s “events are trustworthy enough to automate money.” Set this up once, then validate with real journeys (cart abandon, replenishment, winback) before you roll it out to 100% of traffic.

1. Pick the minimum viable package set for your retention roadmap.
   • Core SDK (required).
   • Add Push if you plan to run cart recovery/reactivation on mobile.
   • Add In-app if you’ll use onsite/app prompts (e.g., “Complete your order” banner when they reopen the app).
2. Install the SDK packages using your platform’s dependency manager (SPM/CocoaPods for iOS, Gradle for Android, npm/yarn for web/React Native). Keep versions aligned across packages—mixed versions are where subtle bugs show up.
3. Initialize the SDK early in the app lifecycle.
   • Do it at app start so you don’t miss first-session events like App Opened or Product Viewed.
   • Set logging to verbose in dev/staging so QA can see identify/track calls firing.
4. Implement identity correctly (this is the money step).
   • Call identify immediately after login/signup.
   • If you support guest checkout or pre-login browsing, track events anonymously first, then identify when they authenticate—so their pre-login browse/cart history can be tied to the same profile.
   • Use a stable, non-changing ID (customer_id is usually safer than email if users can change email).
5. Track a retention-grade event set with consistent naming and properties.
   • Product Viewed: product_id, sku, category, price, currency
   • Add to Cart: product_id/sku, quantity, price, cart_id
   • Checkout Started: cart_id, value, item_count
   • Order Completed: order_id, value, currency, items[]
6. Configure push (if installed).
   • Register device tokens and confirm they attach to the identified profile (not a duplicate).
   • Handle notification opens so you can attribute “clicked push → opened app → purchased.”
7. Validate in Customer.io before shipping.
   • Check a test user profile: confirm attributes, devices, and event stream look correct.
   • Trigger a test campaign off a real event (e.g., Add to Cart) and confirm entry + message delivery.

When Should You Use This Feature

Package selection and configuration options matter most when you’re relying on app behavior to drive revenue—not just sending newsletters. If you’re building triggered programs, the SDK is the source of truth, so you want the right modules installed and identity stitched cleanly.

• Cart abandonment in mobile-first shopping: A shopper adds a cleanser to cart in-app, closes the app, and comes back 6 hours later. If your SDK didn’t capture Add to Cart reliably or didn’t stitch identity after they logged in, your cart recovery audience will be incomplete and your push/email will underperform.
• Browse-to-buy follow-up: You want to send a “Still thinking about running shorts?” message based on Product Viewed frequency. That only works if you’re tracking views with product identifiers and not spamming duplicate events.
• Reactivation: Winback segments like “no app opens in 30 days AND no purchase in 60 days” depend on accurate app lifecycle events and stable identity across reinstalls.
• Repeat purchase + replenishment: If your replenishment timing is based on purchase events, you need Order Completed to be deduped and have clean order_id/value so you don’t trigger the wrong follow-up.

Operational Considerations

In practice, teams don’t fail because they “forgot an event.” They fail because the same user becomes three profiles, or because events arrive late/out of order, or because orchestration depends on properties nobody standardized.

• Segmentation depends on property discipline: If one platform sends productId and another sends product_id, your segments will silently miss people. Lock a schema and enforce it across iOS/Android/web.
• Identity stitching is an orchestration problem: Decide your source-of-truth ID (customer_id vs email). Then make sure every surface (web + app) uses the same identifier so Customer.io doesn’t create parallel people.
• Anonymous-to-known merge strategy: If you allow browsing before login, you need a deliberate plan: track anonymously, then identify at auth. Without this, “viewed product” and “added to cart” end up on an anonymous profile that never receives messages.
• Event timing and retries: Mobile networks drop. If you rely on immediate triggers (like “send push 15 minutes after add-to-cart”), make sure your SDK config and app behavior don’t delay event flushing until the next session.
• Deduplication: Purchases are the classic double-send. If your app fires Order Completed on both “payment success” and “thank you page loaded,” you’ll inflate revenue attribution and mis-trigger post-purchase flows.

Implementation Checklist

Before you call the SDK “done,” run through this checklist like you’re about to spend real money on triggered messaging—because you are.

• Core SDK installed and initialized at app start (staging + production).
• Logging enabled in non-prod to verify identify/track calls.
• identify() called after login/signup with a stable ID; same ID used across web + app.
• Anonymous browsing plan implemented (track first, identify later) if applicable.
• Event schema documented (names + required properties) and implemented consistently across platforms.
• Purchase event deduped with order_id and validated in real checkout flows.
• Push package configured (token registration + open handling) if you’ll use push for recovery/winback.
• Test user profile in Customer.io shows devices, attributes, and expected event stream.

Expert Implementation Tips

These are the small choices that keep your retention engine from drifting over time—especially once multiple engineers touch tracking.

• Prefer customer_id over email for identify when possible. Emails change; IDs don’t. Keep email as an attribute so you can still message.
• Version your schema (even informally). When you change event properties, announce it and update both platforms together. Otherwise segments break and nobody notices until revenue dips.
• Track “cart state” as properties, not just events. For example, include cart_value and item_count on Add to Cart and Checkout Started. It gives you better throttling (“only recover carts over $50”) without extra data plumbing.
• QA with real device behavior: background the app, kill it, toggle airplane mode, reinstall. That’s where identity stitching and event flush issues show up.
• Don’t over-collect automatically: If the SDK offers optional auto-tracking, enable it only if you’ll actually use it for segmentation. Noise makes operators ignore the event stream.

Common Mistakes to Avoid

Most “Customer.io isn’t working” complaints are really SDK configuration mistakes that create bad audiences. Fix these and your automations usually snap into place.

• Calling identify too late (or only on a settings screen). Then all the high-intent events happen anonymously and never trigger recovery.
• Using different identifiers across surfaces: web identifies by email, app identifies by internal ID, and now you’ve got split purchase history and messy frequency caps.
• Inconsistent event naming: Added To Cart vs Add to cart vs AddToCart. Segments and triggers become brittle.
• Double-firing purchase events: this inflates LTV reporting and triggers duplicate post-purchase messages (a fast way to drive unsubscribes).
• Shipping without validating in the Customer.io profile: if you don’t inspect a test user’s event stream, you’re guessing.

Summary

If you’re serious about cart recovery, repeat purchase, and reactivation in-app, SDK packages and configuration options are foundational. Install only what you’ll operationalize, identify users with a stable ID, and make your event schema consistent across platforms. Once that’s clean, Customer.io automation becomes predictable—and that’s when retention lifts compound.

Implement Packages Options with Propel

If you’re rolling out (or cleaning up) SDK tracking for Customer.io, it helps to treat it like a revenue system: identity plan, event schema, QA scenarios, and then orchestration. When you want to sanity-check your package choices and make sure cart/replenishment/winback triggers won’t break under real app behavior, book a strategy call—we’ll review your identify + event flow and map it back to the retention programs you’re actually running.