Migrate from an earlier Customer.io SDK version (mobile/web)

Overview

If you’re migrating from an older SDK, the real risk isn’t “will the app compile”—it’s whether Customer.io keeps recognizing the same customer across sessions, devices, and channels so your retention automations don’t quietly degrade. If you want a second set of eyes on identity stitching and event parity before you flip the switch, book a strategy call and we’ll pressure-test the migration plan like an operator would.

In most retention programs, SDK migrations fail in subtle ways: anonymous browsing stops merging into known profiles, “Added to Cart” fires twice, or purchase events lose item-level payloads—then cart recovery and post-purchase upsells underperform and nobody ties it back to the SDK change.

How It Works

SDK migration is mostly about preserving three things: (1) how you initialize the SDK, (2) how you identify users, and (3) how events are named and shaped. Customer.io uses those inputs to stitch activity into a single person profile and to qualify people into segments that drive recovery and repeat-purchase journeys.

• Initialization: the app loads the Customer.io SDK with your workspace credentials and environment settings. If initialization changes (or runs late), early-session events can get lost or attributed incorrectly.
• Identity stitching: anonymous activity (pre-login) needs to merge into the known customer once you call identify. If you change when/with what identifier you call identify, you often create duplicates—one profile that abandoned the cart and another that later purchased.
• Event parity: your journeys depend on consistent event names and payload keys. If your old SDK sent add_to_cart and the new one sends Added To Cart, your “Cart Abandonment” entry trigger won’t fire. Same story if you stop sending sku, price, quantity, or order_id.
• Device/channel linkage: mobile SDKs also manage device tokens (push) and sometimes in-app context. If device registration shifts, your reactivation pushes can drop even while email looks fine.

Step-by-Step Setup

Treat this like a data migration, not a library upgrade. The goal is to run old vs new in a controlled way, prove identity and event parity, then cut over without breaking live automations.

1. Inventory what retention depends on today
   Pull a list of the exact event names and key payload fields used in: cart recovery, browse abandonment, post-purchase, replenishment, winback, and VIP segmentation. Also list the person attributes you rely on (e.g., email, phone, first_order_date, last_order_date, lifetime_value).
2. Install the current SDK in a migration branch
   Add the new Customer.io SDK to your iOS/Android/Web app per the latest install docs for your platform. Keep the old implementation intact until you’ve validated parity.
3. Replicate initialization timing
   Initialize as early as you can in app startup—before you emit any “session start”, “product viewed”, or “collection viewed” events. In practice, cart recovery breaks when product/browse events fire before the SDK is ready.
4. Lock down your identity strategy (this is the make-or-break)
   Decide the canonical identifier you’ll use with identify (typically a stable internal customer ID). Then:
   • Call identify immediately after login/signup (and after you have the stable ID).
   • Also call identify on app launch if you have a persisted authenticated session.
   • Attach channel identifiers consistently (email/phone) as attributes so messaging can route correctly.
5. Mirror event names and payload shape
   Implement track calls for the same events you used previously, keeping naming identical. For commerce events, send item arrays and order metadata consistently. Example payload expectations you should preserve:
   • product_viewed: product_id, sku, name, category, price
   • add_to_cart: cart_id, sku, quantity, price
   • checkout_started: cart_id, value, items
   • order_completed: order_id, value, currency, items, discount_code
6. Prevent double-firing during the transition
   If you temporarily run both old and new tracking paths, gate one behind a feature flag so you don’t emit duplicate events. Duplicate add_to_cart events will inflate intent signals and spam recovery flows.
7. Validate in Customer.io before releasing
   Use a test account and run a full scenario: anonymous browse → add to cart → login → purchase. Confirm in the person profile that:
   • Anonymous activity merges into the identified profile after identify.
   • Events appear once (no duplicates) and with the expected payload.
   • Attributes update as expected (email/phone, last_order_date, etc.).
8. Roll out gradually and monitor journey entry rates
   Release to a small percentage of users first. Watch key operational metrics: cart abandonment journey entrants, purchase-confirmation triggers, winback eligibility counts, and push deliverability (device token registration).

When Should You Use This Feature

SDK migration work is worth doing when the upside is better data integrity and channel reach—not just “being on the latest version.” The best timing is when you’re already seeing attribution gaps or you’re about to scale spend and need retention to hold.

• Your cart recovery flow is under-triggering: e.g., Shopify shows 1,000 abandoned checkouts/week but Customer.io only sees 600 checkout_started events. Migration is often the moment to fix event coverage and timing.
• You’re seeing duplicate profiles: customers receive both “welcome” and “winback” because anonymous and logged-in identities never merged cleanly.
• You’re expanding channels: adding push/in-app requires rock-solid device registration and consistent identify calls.
• You’re rebuilding your event taxonomy: if you’re standardizing events (browse → cart → checkout → purchase), do it during the SDK upgrade so you only QA once.

Real D2C scenario: A skincare brand’s app drives 35% of revenue. After an SDK upgrade, their “Added to Cart” events started firing before login and never merged, so the cart abandonment journey stopped emailing logged-in customers. Fixing the identify timing (identify on app launch when a session exists, not only on explicit login) restored recovery revenue within a week.

Operational Considerations

Once the SDK is live, the operational reality is that your segmentation and orchestration are only as good as the identity and event stream. Plan for the downstream impact before you ship.

• Segmentation stability: keep event names stable or update every segment/journey trigger that references them. Even a small rename can zero out a high-value segment like “Viewed product 2+ times in 7 days.”
• Data flow timing: mobile apps often queue events offline. Make sure your SDK flush behavior doesn’t delay “checkout_started” by hours—otherwise your 30-minute cart reminder becomes a next-day reminder.
• Identity precedence: decide whether email or internal ID is the source of truth. In practice, using internal ID for identify and storing email as an attribute reduces collisions when customers change emails.
• Cross-device stitching: if customers browse on mobile web then purchase in-app, align identifiers across implementations (web SDK vs mobile SDK) so Customer.io can tie the journey together.
• Orchestration realities: if you trigger journeys off app events, be careful with “retry” logic that can resend events (and re-enter journeys). Add idempotency keys like order_id and guardrails in workflows.

Implementation Checklist

Before you call the migration “done,” you want proof that retention-critical signals still fire correctly and stitch to the right person.

• New SDK installed and initialized early in app lifecycle
• identify called with a stable customer ID after login and on app launch when authenticated
• Email/phone captured as person attributes (and kept current)
• Event names match your existing taxonomy exactly
• Commerce payloads include cart_id, order_id, items, value, currency
• No duplicate event emission during rollout (feature flag or hard cutover)
• Test scenario verified in Customer.io profile (anonymous → identified merge)
• Key journeys monitored post-release (entry rate, conversions, suppression)

Expert Implementation Tips

The teams that get this right treat tracking like product infrastructure: versioned, tested, and observable.

• Version your events: add an event_source_version attribute or event property during rollout. When metrics shift, you can isolate whether the new SDK is the cause.
• Build an “event parity” dashboard: compare counts of product_viewed, add_to_cart, checkout_started, order_completed before vs after release. This catches silent drops fast.
• Use idempotency for purchases: always send order_id and have your orchestration guard against re-processing the same order event.
• Don’t rely on UI events alone: track “business events” (cart updated, checkout started) from the source of truth in your app state, not just button clicks. Button-click tracking tends to break when UI changes.

Common Mistakes to Avoid

Most migration issues show up as revenue problems days later, because the workflows are still “running”—they’re just running on bad data.

• Changing event names during migration without updating segments, triggers, and filters everywhere they’re referenced.
• Calling identify with email in one client and internal ID in another, creating fractured profiles and inconsistent suppression.
• Identifying too late (after key events fire), which prevents anonymous activity from merging into the customer profile you actually message.
• Double-sending events during phased rollouts, causing customers to re-enter recovery journeys and inflating intent scoring.
• Dropping item-level payloads (SKUs, quantities), which kills personalized cart and post-purchase recommendations.
• Not validating device token registration after migration, leading to “reactivation push” volume collapsing while email masks the issue.

Summary

Migrating an older Customer.io SDK is an identity-and-events project disguised as a dependency upgrade. Preserve identify behavior, keep event names/payloads consistent, and validate anonymous-to-known merging. If your cart recovery and repeat purchase flows depend on app events, treat parity testing as a release gate—not a nice-to-have.

Implement Migrate Upgrade with Propel

If you’re upgrading the SDK because retention performance has drifted—or you’re about to scale acquisition and need tighter recovery—bring your tracking plan and we’ll sanity-check identity stitching, event parity, and downstream journey triggers in Customer.io. When you’re ready, book a strategy call and we’ll walk through the migration like we’re on the hook for revenue, not just “successful implementation.”