Get Started with the Customer.io SDK (2.x) for Retention Tracking

Overview

If you’re running retention in a D2C business, the Customer.io SDK setup is where most programs either get clean leverage—or quietly bleed revenue through broken identity stitching and missing events. If you want a second set of eyes on your tracking plan before you scale automations, you can book a strategy call and we’ll pressure-test your event map against the campaigns you actually want to run.

At a practical level, your goal is simple: capture high-signal app behavior (browse, add-to-cart, checkout start, purchase) and reliably tie it to the same person once they log in or enter email/SMS. That’s what makes cart recovery work in-app and in inbox, and it’s what unlocks repeat purchase flows that don’t feel random.

How It Works

The SDK sits inside your mobile app (or web app) and sends two kinds of data to Customer.io: who the person is (identity + attributes) and what they do (events). In most retention programs, we’ve seen the biggest lift come from getting the identity moments right—because without that, your “abandoned cart” audience is split across anonymous profiles and known profiles, and your messaging hits late or not at all.

• Anonymous activity first, then stitched: A new user can browse and add to cart before they ever log in. The SDK records that behavior as anonymous activity. Once you call identify (typically at login, account creation, or email/SMS capture), Customer.io can merge that anonymous history into the known person—so your cart recovery doesn’t reset to zero.
• Identify calls create the “source of truth” person: When you identify, you pass a stable identifier (usually your internal user ID) and optionally traits (email, phone, first order date, marketing opt-in). That’s what your segments and orchestration will actually key off.
• Event tracking drives segmentation + triggers: Events like Product Viewed, Added to Cart, Checkout Started, and Order Completed become the building blocks for “entered checkout but didn’t buy in 2 hours” or “bought once 45–60 days ago” audiences.
• Devices matter for push + in-app: The SDK also helps associate devices with people. If device association is inconsistent (common when identify is delayed), push/in-app audiences won’t match your email audiences—and you’ll see weird gaps in recovery flows.

Real D2C scenario: A shopper installs your app, views two products, adds one to cart, then bounces. The next day they open the app again and create an account to check shipping. If you only identify at account creation but don’t merge anonymous activity, Customer.io sees a “new” user with no cart—so your cart recovery never fires. With correct SDK identity stitching, the cart event history follows them, and you can trigger a push within minutes and an email fallback if they don’t convert.

Step-by-Step Setup

Before you touch campaigns, get the plumbing right. You’re aiming for a clean, minimal event schema that maps directly to revenue-critical automations, and an identity strategy that doesn’t fragment users across profiles.

1. Install the Customer.io SDK in your app
   Add the SDK for your platform (iOS/Android/React Native/Flutter, etc.) and initialize it as early as practical in the app lifecycle so you don’t miss first-session events.
2. Define your identity strategy (this is the make-or-break step)
   Pick a stable primary identifier (typically your internal user ID). Decide when you will call identify:
   • Login
   • Account creation
   • Email capture (even before full registration, if you support it)
   • SMS capture (if you support it)
   In practice, delaying identify until “purchase” is a common reason cart recovery underperforms—because you’re identifying too late.
3. Call identify and pass core traits
   At identify time, send traits you’ll actually segment on (don’t dump your whole user table):
   • email (if you have it)
   • phone (if opted in)
   • marketing_opt_in (channel-specific if possible)
   • country / timezone (helps send-time logic)
   • first_order_date, last_order_date (if you maintain them reliably)
4. Track a small set of high-signal commerce events
   Start with the events you’ll orchestrate immediately:
   • Product Viewed (include product_id, category, price)
   • Added to Cart (include product_id, quantity, cart_value)
   • Checkout Started (include cart_value, item_count)
   • Order Completed (include order_id, revenue, items, discount, shipping)
   Keep naming consistent and properties predictable—segment logic breaks fast when one platform sends productId and the other sends product_id.
5. Verify identity stitching and event arrival in Customer.io
   Test the full path: anonymous browse → add to cart → identify → confirm the same person profile shows pre-identify events. If this fails, your cart recovery and browse retargeting will be unreliable.
6. Create your first segments and triggers based on those events
   Only after validation, build segments like “Added to Cart in last 4 hours AND no Order Completed in last 4 hours” and use them to trigger your recovery workflow.

When Should You Use This Feature

The SDK matters most when you need app-side behavior to drive retention outcomes in near real-time. If your retention program relies on “what the customer did in the app,” the SDK becomes your source of truth—not your ecommerce platform’s nightly export.

• Cart and checkout recovery from app behavior: Trigger push/in-app immediately after Checkout Started, then fall back to email/SMS if no purchase event arrives.
• Product discovery loops: When someone views a category 3+ times but doesn’t add to cart, you can route them into a “help me choose” flow (education + social proof), not a discount blast.
• Post-purchase replenishment and cross-sell: Use Order Completed item data to drive timed reorders (e.g., skincare at 30 days) or accessories upsells (e.g., “you bought the device, here are refills”).
• Reactivation based on last meaningful action: “No Product Viewed in 21 days” is often a better reactivation trigger than “no purchase,” especially for higher-consideration products.

Operational Considerations

Once the SDK is live, the day-to-day retention work is mostly about keeping data consistent enough that your segments and orchestration don’t drift. The teams that win are the ones who treat event design like a product surface, not a one-time engineering ticket.

• Segmentation depends on event hygiene: If iOS fires Added to Cart on button tap but Android fires it only after the cart API succeeds, your “abandoners” will skew by platform. Align definitions across platforms.
• Identity stitching is fragile around guest checkout: If users can check out as guests, decide how you’ll map that to a person. If email is collected at checkout, identify as soon as you have it—waiting until order completion is too late for recovery.
• Orchestration reality: events arrive out of order
  Mobile networks and background states can delay events. Build workflows with short buffers (e.g., wait 10–20 minutes before declaring abandonment) and use “purchase happened” exit conditions.
• Attribute vs event tradeoffs: Don’t overload attributes with constantly changing data like cart contents. Keep cart state in events (or an object model) and use attributes for stable segmentation fields.
• Cross-channel consistency: Your push audience is only as good as your device association. If your identify call happens late, you’ll see email/SMS hitting but push missing—especially in cart recovery.

Implementation Checklist

If you want this to drive revenue, treat the checklist below like your “definition of done.” It’s the difference between having data in Customer.io and having data you can actually orchestrate against.

• SDK installed and initialized early enough to capture first-session behavior
• Clear identify moment(s) defined (login, signup, email capture, checkout email)
• identify sends a stable user ID + channel traits (email/phone) when available
• Anonymous-to-known merge validated with a real test journey
• Core commerce events tracked with consistent naming and property schema
• Purchase event includes order_id and revenue (so conversion reporting is clean)
• Basic abandonment segments built and sanity-checked against real user counts
• Workflow exit conditions added (stop messaging once Order Completed fires)

Expert Implementation Tips

Most teams don’t lose performance because they “lack automations.” They lose it because the tracking layer creates edge cases that quietly suppress sends or misclassify customers.

• Identify earlier than you think: If you have an email capture modal or “save cart” flow, identify there. That’s how you turn anonymous carts into recoverable carts.
• Standardize event properties across platforms: Write a single event contract (names + required properties) and enforce it in code review. This prevents segment logic from turning into platform-specific hacks.
• Use short holding periods before abandonment messaging: A 10–30 minute delay catches “I got interrupted” behavior and reduces false positives, especially on mobile where app switching is constant.
• Send item arrays on purchase events: If you want real post-purchase personalization (cross-sell, replenishment), you need line-item detail on Order Completed, not just revenue.
• Plan for identity merges and duplicates: In practice, this tends to break when users log in with Apple private relay, change emails, or reinstall the app. Decide what ID is canonical and stick to it.

Common Mistakes to Avoid

These are the issues that show up later as “why is our cart recovery down?” or “why are segments tiny?”—and they almost always trace back to SDK behavior.

• Calling identify only after purchase: You’ll miss the entire recovery window for carts and checkouts.
• Using email as the primary ID: Emails change, get aliased, or are missing pre-checkout. Use an internal user ID as primary, attach email as a trait.
• Inconsistent event naming: add_to_cart vs Added To Cart sounds minor until you build segments and half your audience disappears.
• Tracking too many low-signal events: Flooding Customer.io with noisy events makes debugging harder and doesn’t improve retention outcomes. Start with the events you’ll actually trigger campaigns from.
• No exit conditions in recovery workflows: If you don’t stop messaging when a purchase occurs, you’ll discount people who already bought and train them to wait.

Summary

If you want Customer.io to drive repeat purchase and recovery from app behavior, the SDK implementation is the foundation: early identify, clean event contracts, and verified anonymous-to-known stitching.

When those three are solid, your segments stay stable, your workflows trigger on time, and your channel mix (push/email/SMS) behaves predictably.

Implement 2.x with Propel

If you’re implementing the 2.x SDK and want it to translate into revenue (not just “events showing up”), we usually start by mapping your top 3 retention motions—cart recovery, second purchase, and reactivation—back to the exact identify moments and events required in Customer.io.

If that’s useful, book a strategy call and we’ll review your current tracking, where identity is fragmenting, and what to fix before you scale spend or discounting.