Migrate from an earlier version (Mobile SDKs)

Overview

If you’re migrating an older Customer.io mobile SDK, the real risk isn’t “does the app compile?”—it’s whether your identity stitching and event stream stay consistent enough to keep cart recovery, post-purchase, and winback automations firing the way you expect. If you want a second set of eyes on the migration plan (especially around identify timing and duplicate profiles), book a strategy call and we’ll pressure-test it like an operator would.

In most retention programs, SDK migrations go sideways when anonymous activity stops merging, device tokens get orphaned, or event names drift—then your segments quietly hollow out and revenue drops before anyone notices.

How It Works

SDK migration is mostly about preserving the contract between your app and Customer.io: how you identify a person, how you attach a device, and how you emit events that downstream campaigns depend on. When you upgrade, you’re typically changing one (or more) of these moving parts: initialization, identify calls, push token registration, and event payload structure.

• Initialization sets the workspace + environment context. If your site ID/API key or region endpoints change (or you accidentally point staging at prod), you’ll see clean installs but “wrong audience” sends later.
• identify() is the stitching moment. The SDK associates the current device/session with a stable customer identifier (usually your internal user ID, sometimes email). If identify happens late—or not at all for guest checkout flows—anonymous events won’t merge into the known profile, and cart/browse recovery becomes unreliable.
• Event tracking is your retention fuel. Your campaigns trigger on specific event names and properties. If the migration changes names (e.g., Added To Cart → add_to_cart) or drops properties (like sku, cart_value), you’ll still “send events,” but your segmentation and branching logic won’t match.
• Device management impacts push deliverability. Upgrades can change how device tokens are registered or how multiple devices attach to a profile. If tokens don’t get re-registered after upgrade, push audiences shrink and your fastest recovery channel underperforms.

Real D2C scenario: You run a 30-minute cart abandonment push + email. After an SDK upgrade, cart events still show up in logs, but the push step drops 40% because the app now identifies only after account creation—not after guest email capture. The fix isn’t “send more”—it’s moving identify() earlier and ensuring anonymous-to-known merge still happens.

Step-by-Step Setup

Plan the migration like you’d plan a pricing test: protect the revenue flows first, then ship the code. The goal is to upgrade the SDK while keeping identifiers, event names, and device tokens consistent enough that your existing automations don’t need to be rebuilt.

1. Inventory what your retention program depends on
   • List the exact event names your automations use (cart, checkout, purchase, product viewed, subscription events).
   • List required properties (SKU, product_id, price, currency, cart_id, order_id, email, phone, attribution fields).
   • List identify sources (user_id vs email) and when they occur (login, signup, checkout, email capture).
2. Upgrade the SDK in your app (staging first)
   • Update iOS/Android dependencies to the target Customer.io SDK version.
   • Confirm initialization uses the correct site ID and keys for the environment.
   • Keep your existing event names and payload schema intact unless you’re intentionally versioning them.
3. Re-validate identify() timing and identifier choice
   • Call identify() as soon as you have a stable identifier (ideally internal user ID; email is a fallback when you truly don’t have one).
   • If you support guest checkout, identify at email/phone capture—don’t wait for account creation.
   • Ensure you’re not flipping identifiers across sessions (e.g., sometimes email, sometimes user_id) without a clear mapping strategy.
4. Verify anonymous → known merging still works
   • Test: browse anonymously → add to cart → then login/enter email → confirm earlier events attach to the known profile.
   • Spot-check in Customer.io activity logs that events appear under the final identified person, not stranded under an anonymous profile.
5. Re-confirm push token registration after upgrade
   • Install fresh on a device, opt into push, and confirm the device shows on the person profile.
   • Upgrade an existing install and confirm the token remains associated (or is re-registered) without creating duplicate device entries.
6. Run an end-to-end retention flow test
   • Trigger cart abandonment (event → delay → push/email) and confirm both eligibility and delivery.
   • Trigger post-purchase cross-sell and confirm order properties are still present for personalization.

When Should You Use This Feature

You migrate SDK versions when the current setup is holding back tracking accuracy, push reliability, or identity stitching. The best time to do it is before you scale spend or launch a new retention motion—because broken identity makes every downstream experiment noisy.

• Your cart recovery performance is drifting and you suspect device tokens or identify timing changed over time (common after app refactors).
• You’re adding new retention triggers (browse abandonment, back-in-stock, replenishment) and need cleaner event payloads and consistent schemas.
• You’re seeing duplicate people in Customer.io because identifiers are inconsistent across app states (guest vs logged-in).
• You’re modernizing push and need reliable device registration and multi-device support for the same customer profile.

Operational Considerations

SDK migration is a data migration in disguise. If you don’t manage segmentation and orchestration realities during the cutover, you’ll end up debugging “why did revenue drop?” instead of shipping improvements.

• Segmentation stability: If segments rely on “event occurred within X days,” any event-name drift or missing properties will quietly remove people from audiences. Freeze naming during migration and version intentionally if you must change.
• Identity stitching: Decide on a primary identifier (preferably internal user ID). In practice, mixing email and user_id without a mapping plan creates duplicates that inflate audience counts and break frequency controls.
• Data flow validation: Watch real-time event ingestion and person activity logs during the rollout window. Don’t rely on “we see events” as success—confirm they land on the right profile.
• Orchestration impact: If you run multi-step flows (push → email → SMS), a break in device association can make the journey look “fine” while channel mix collapses. Monitor channel-level delivery, not just journey entries.
• Rollout strategy: If possible, staged rollout (percentage-based release) reduces blast radius and makes it easier to compare pre/post behavior.

Implementation Checklist

Before you ship the upgraded SDK to 100% of users, lock this checklist. It’s the difference between a clean upgrade and a month of chasing phantom drops in cart recovery.

• Event name map documented (old → new), ideally unchanged
• Required event properties confirmed for: product viewed, add to cart, checkout started, purchase
• identify() called at the earliest stable moment (login, signup, or guest email capture)
• Anonymous browsing/cart events merge into the identified profile after identify
• Push token registers on fresh install and survives app upgrade
• No spike in duplicate profiles during staging tests
• At least one full cart abandonment journey tested end-to-end (eligibility + delivery)
• Post-purchase journey tested with personalization fields (order_id, items, value)
• Monitoring plan in place for first 48–72 hours (event volume, journey entries, channel delivery)

Expert Implementation Tips

Most teams focus on “SDK upgraded” and miss the retention-critical edge cases. These are the moves that keep your automations stable while you modernize tracking.

• Identify earlier than you think you need to. For D2C, the highest-value moments often happen pre-login (browse, cart, checkout). If you collect email for “save my cart,” that’s your identify moment.
• Keep event schemas boring. Don’t rename events during an SDK migration unless you’re also updating every campaign trigger, segment, and report that depends on them.
• Version intentionally when you must change. If you need a new payload, create add_to_cart_v2 temporarily and run both in parallel until campaigns migrate, then deprecate.
• Watch for silent property loss. The most common break is not missing events—it’s missing product_id or order_id, which kills deduping and personalization.
• Test upgrade paths, not just fresh installs. A lot of your audience will update the app, not reinstall it. That’s where token association and identity persistence tend to break.

Common Mistakes to Avoid

These are the failure modes that show up as “our journeys stopped working” even though engineering swears events are flowing.

• Changing identifiers mid-stream (email in one flow, user_id in another), creating duplicates and splitting event history.
• Delaying identify until after purchase, which strands cart and checkout events under anonymous profiles and weakens recovery.
• Renaming events without updating triggers, causing segments and journeys to stop matching quietly.
• Dropping key properties like currency, value, sku/product_id—your messages send, but personalization and branching fail.
• Not validating push tokens post-upgrade, leading to a sudden drop in push reach and slower recovery cycles.
• Only monitoring top-line event volume instead of verifying events attach to the correct person profile.

Summary

Migrating an earlier Customer.io SDK version is a retention-critical change because it touches identity, events, and devices—the three things your automations run on. Treat it like a data contract upgrade: preserve identifiers, keep event schemas stable, and validate anonymous-to-known merging before you roll out.

Implement Migrate Upgrade with Propel

If you’re upgrading a mobile SDK and want to avoid the usual identity and event pitfalls, we’ll review your tracking plan the same way we’d review a revenue-sensitive cart recovery flow. That typically means validating identify() timing, event/property parity, and device token behavior against your live Customer.io journeys—then giving you a rollout and monitoring plan your team can actually execute. If that’s helpful, book a strategy call.