Get Started with Customer.io SDK 1.x (Install, Identify, Track Events)

Overview

If you’re using Customer.io for retention, the SDK is where the program either becomes reliable—or turns into a constant game of “why didn’t this person enter the flow?” If you want a second set of eyes on identity stitching and event design before you scale sends, book a strategy call and we’ll pressure-test the tracking plan like an operator would.

At a practical level, SDK setup is about three things: getting the library installed cleanly, calling identify at the right moments so profiles merge correctly, and tracking a small set of high-signal events that map directly to cart recovery, repeat purchase, and reactivation.

How It Works

Customer.io’s SDK sits inside your app (mobile or web) and sends two types of data: who the person is (identity + attributes) and what they do (events). Retention performance depends on how consistently you send both—especially across anonymous browsing, login, checkout, and post-purchase.

• Installation creates the pipe. Once the SDK is initialized, it can send events and profile updates to your workspace.
• identify is the stitching moment. Before login/checkout, you’ll often have anonymous activity. The moment you know who the shopper is (email capture, account login, checkout), you call identify with a stable identifier so Customer.io can connect past behavior to the right profile.
• Events power entry into campaigns. Customer.io automations (campaigns/workflows/journeys) typically trigger off events like Added to Cart, Checkout Started, Order Completed, or Viewed Product.
• Attributes power segmentation and suppression. Things like last_order_at, orders_count, sms_opt_in, push_token, preferred_category, and lifetime_value are what keep your recovery and winback programs from blasting everyone.

Real D2C scenario: a shopper browses leggings in your app, adds a size/color to cart, then bounces. If you only track the cart event anonymously and never stitch it at email capture, your cart recovery flow won’t fire (or it’ll fire to an “unknown” profile). When identify happens immediately after email capture (or login), Customer.io can merge that anonymous cart activity into the known profile and your recovery journey triggers correctly.

Step-by-Step Setup

Before you touch campaigns, get the SDK sending clean, consistent data. Most retention issues we see later trace back to “we installed it” but didn’t standardize identity and event payloads.

1. Create your workspace and confirm channels.
   Even if you’re SDK-first, make sure your workspace exists and you’ve set up the channels you’ll actually use (email, push, SMS). Otherwise teams start building flows that can’t send.
2. Install the correct SDK for your app.
   Pick the platform SDK (iOS/Android/React Native/Flutter/Web) that matches your stack. Install it using your normal dependency manager and initialize it at app start so events don’t drop on cold opens.
3. Define your primary identifier strategy.
   Decide what id means in your app:
   • If you have accounts: use your internal user ID as the primary identifier and store email as an attribute.
   • If you’re email-first: use email as the identifier, but be strict about normalization (lowercase, trimmed) to avoid duplicates.
4. Implement identify at the right moments.
   Call identify when you have a durable identity:
   • Account creation
   • Login
   • Email capture (newsletter modal, checkout email step)
   • Order completion (as a backstop)
   Include core attributes you’ll segment on (e.g., email, phone, timezone, marketing_opt_in, first_seen_at).
5. Track a minimal, retention-grade event schema.
   Start with events that map directly to money:
   • Product Viewed (include product_id, category, price)
   • Added to Cart (include cart_id, line items, value)
   • Checkout Started (include cart_id, value, shipping country)
   • Order Completed (include order_id, revenue, items, discount code)
   Keep names stable. Changing event names later breaks triggers and reporting.
6. Confirm devices/tokens are captured for messaging.
   For push/in-app, make sure device tokens and permissions status are being associated with the identified profile—otherwise you’ll “send” push that never delivers.
7. Validate in Customer.io before building workflows.
   Open a test profile in Customer.io and confirm:
   • Attributes show up as expected
   • Events arrive with the right payload
   • Anonymous activity merges after identify

When Should You Use This Feature

The SDK matters most when your retention program depends on behavioral triggers and cross-session continuity. If you’re only sending batch newsletters, SDK work is optional; if you’re running cart recovery, replenishment, or winback, it’s foundational.

• Cart recovery that actually matches the cart. Trigger off Added to Cart/Checkout Started and personalize with items, not generic “you left something behind.”
• Post-purchase repeat purchase and cross-sell. Use Order Completed payload + category data to drive the next-best offer (e.g., socks after sneakers, refills after supplements).
• Reactivation based on product discovery signals. If someone views a category 3 times but hasn’t purchased, that’s a clean reactivation segment—assuming the identity is stitched.
• Channel expansion (push/SMS) without spamming. SDK-collected device + consent attributes let you suppress correctly and sequence channels (push first, email fallback).

Operational Considerations

In most retention programs, the hard part isn’t sending messages—it’s keeping data clean enough that segmentation and orchestration don’t degrade over time. Treat the SDK as production infrastructure, not a one-time integration.

• Segmentation depends on stable fields. Pick a small set of canonical attributes (e.g., orders_count, last_order_at, lifetime_value, sms_opt_in) and don’t let every engineer invent new variants.
• Event timing affects recovery windows. If Checkout Started fires late (or only on a confirmation screen), your “1 hour abandonment” email becomes a “next day” email.
• Identity stitching breaks quietly. The most common failure mode is duplicate profiles (email case differences, multiple IDs, identify called too late). That leads to suppressed sends, mis-attribution, and people getting the wrong message.
• Orchestration needs suppression rules. Once events are flowing, you’ll likely have multiple journeys eligible at once (browse abandon + cart abandon + winback). Decide priority and add exit conditions (e.g., exit cart flow on Order Completed).
• Payload design impacts personalization. If you don’t include line items and value in cart/order events, you’ll be stuck with generic creative and weaker conversion.

Implementation Checklist

If you want this to hold up once you start scaling campaigns, run through this checklist before you ship the integration to all users.

• SDK installed and initialized at app start (no missing events on first session)
• Single, documented primary identifier strategy (internal ID or normalized email)
• identify implemented at login/account creation and at least one backstop moment (checkout/order)
• Anonymous-to-known merge validated on a real device
• Core events implemented: Product Viewed, Added to Cart, Checkout Started, Order Completed
• Event payloads include IDs + value + item details needed for message personalization
• Consent and channel readiness tracked (email opt-in, SMS opt-in, push permission, device token)
• Test profile in Customer.io shows correct attributes, events, and device association

Expert Implementation Tips

These are the operator moves that keep your retention engine stable once you have multiple journeys, multiple channels, and a team making changes every week.

• Normalize identifiers at the source. Lowercase/trim emails before calling identify. It’s boring—and it prevents months of duplicate-profile cleanup.
• Use one cart ID across the funnel. If Added to Cart uses cart_id=A and Checkout Started uses cart_id=B, your recovery logic can’t reliably dedupe or personalize.
• Send “state” as attributes, not events. Things like is_subscriber, vip_tier, preferred_size belong as attributes so segmentation stays simple.
• Design for suppression early. Add Order Completed as a global exit for cart/browse flows. In practice, this tends to break when teams add new purchase paths (Shop Pay, PayPal, in-app checkout) and forget to fire the purchase event.
• QA with real journeys, not just “event received.” Fire the event, confirm the person enters the workflow, confirm the message renders with payload data, then confirm they exit on purchase.

Common Mistakes to Avoid

Most “Customer.io isn’t working” complaints are really SDK implementation gaps. Fix these and your campaigns start behaving predictably.

• Calling identify too late. If you only identify on order completion, you lose cart recovery for first-time buyers who abandon before purchase.
• Using multiple identifiers without a plan. Email in one place, internal ID in another, phone elsewhere—this creates duplicates and inconsistent suppression.
• Event names that drift. Shipping AddedToCart on Android and Added to Cart on iOS forces you to build brittle triggers and segments.
• No payload for personalization. Tracking Added to Cart without items/value guarantees generic messages and lower recovery rates.
• Forgetting consent/device state. Sending push flows without tracking permission/token leads to “sent” metrics with weak delivery and confused stakeholders.

Summary

If you want reliable cart recovery, repeat purchase, and reactivation in Customer.io, the SDK setup is the foundation. Install cleanly, stitch identity early with identify, and track a small set of high-signal events with payloads you can actually use in messages.

Implement 1.x with Propel

If you’re rolling out SDK 1.x and want to avoid the usual identity and event-schema pitfalls, we can help you map tracking to the actual retention journeys you plan to run in Customer.io. When it’s helpful, book a strategy call and we’ll review your identify moments, event payloads, and suppression logic before you scale volume.