Packages and Configuration Options (SDK): what to install, what to track, and how to keep identity clean

Overview

If you’re running retention in Customer.io, your SDK package choices and configuration details are what decide whether cart recovery and repeat purchase flows fire cleanly—or quietly miss people. If you want a second set of eyes on the tracking plan before you ship, book a strategy call and we’ll pressure-test identity stitching, event naming, and the data you actually need for retention.

In most D2C programs, the biggest wins come from getting three things right early: (1) install the right SDK modules for your channels, (2) identify users at the right moment, and (3) track a small set of high-signal events consistently across app + web.

How It Works

Customer.io’s SDK “packages” are basically the building blocks you ship in your app (and sometimes web) so you can send behavioral data into Customer.io and reliably message the same person across sessions and devices. In practice, this tends to break when teams treat SDK setup like “analytics plumbing” instead of retention infrastructure—especially around anonymous users and login/signup.

• Installation determines capability. The base SDK handles core tracking + identity. Add-ons/modules handle specific channels (push, in-app) and behaviors (deep links, device tokens, etc.). If you don’t include the right package, you’ll later wonder why a push journey can’t target the right device.
• Identity stitching is the retention unlock. A shopper can browse anonymously, add to cart, then log in later. Your SDK needs to track anonymous activity and then merge it into the known profile when you call identify. That’s what makes “browse abandon” and “cart abandon” work for logged-in users without losing the earlier context.
• Events and attributes drive segmentation. Journeys don’t run on vibes—they run on event payloads (e.g., product_id, cart_value) and person attributes (e.g., last_order_date, vip_tier). Your package/config choices should support consistent event delivery and accurate timestamps.

Step-by-Step Setup

You’re aiming for a setup that’s boringly reliable: same user ID everywhere, consistent event names, and no gaps between anonymous and known behavior. Set this up once and your retention programs stop fighting the data.

1. Pick your “source of truth” identifier.
   Use a stable internal customer ID (not email) as the primary identifier. Email changes; IDs shouldn’t. Decide this before implementation so you don’t create duplicates later.
2. Install the SDK package(s) you actually need.
   At minimum, install the core SDK for your platform (iOS/Android/Web). Add the push module if you’ll send push, and the in-app module if you’ll run in-app messages. If you’re only doing email today, still install the core SDK—email performance improves when behavior and identity are clean.
3. Initialize the SDK early in app startup.
   Initialize on app launch so you capture first session events (product views, category views, search) and can attribute them to an anonymous profile before login.
4. Track anonymous behavior immediately.
   Track high-intent events even before a user logs in:
   • Product Viewed (include product_id, category, price)
   • Added to Cart (include cart_id, items, cart_value)
   • Checkout Started (include cart_value, shipping_method if available)
5. Call identify at the moment the user becomes “known.”
   Do this on login/signup and on any point where you can confidently tie the device/session to the customer record. Include key attributes you’ll segment on (e.g., email, phone, marketing_opt_in, vip_tier).
6. Confirm anonymous-to-known merge behavior.
   After identify, validate that pre-login events appear on the known profile. This is the difference between a cart recovery flow that converts and one that misses half your carts.
7. Register push tokens (if using push) and keep them updated.
   Device tokens rotate. Make sure your push module updates tokens and associates them to the identified profile, or you’ll see “sent” pushes with no opens because the device mapping is stale.
8. Standardize event names + payload schema.
   Lock a naming convention (e.g., Title Case events, snake_case properties) and document required properties. Retention automations fail when one platform sends productId and another sends product_id.
9. QA with real scenarios, not test pings.
   Run through: browse → add to cart → close app → reopen → login → purchase. Then check the profile timeline and confirm the journey triggers and filters behave exactly as expected.

When Should You Use This Feature

SDK package/config work is worth doing whenever you need Customer.io to react to in-app behavior in near real time and you care about stitching behavior across devices and sessions. If your retention program depends on “what they did” (not just “who they are”), this is foundational.

• Cart recovery from the app (high intent). Example: a shopper adds a bundle to cart on mobile, gets distracted, and closes the app. With correct anonymous tracking + identify merge, your journey can send push within 30 minutes and email later if they’re opted in.
• Product discovery → repeat purchase loops. Track Product Viewed and Category Viewed to build segments like “viewed skincare 3+ times, no purchase in 14 days” and run replenishment or education sequences.
• Reactivation based on app inactivity. If you rely on App Opened or session events, SDK accuracy matters. Otherwise you’ll misclassify active users as dormant and burn them with pointless winback offers.
• Cross-device identity (web + app). If a customer browses on web and buys in-app (or vice versa), consistent IDs and identify timing prevent fragmented profiles and broken frequency controls.

Operational Considerations

Once the SDK is live, the real work is keeping the data usable for segmentation and orchestration. Most teams don’t fail on installation—they fail on consistency and governance after the first few releases.

• Segmentation depends on property hygiene. Decide which properties are required for each event (e.g., Added to Cart must always include cart_value and items). If those are optional, your “cart value > $75” segment becomes unreliable.
• Data flow timing affects journey triggers. Mobile networks are messy. If events batch or arrive late, your “send after 30 minutes” cart flow might fire after the customer already purchased. Build guardrails: purchase exit conditions and short “wait until no purchase” checks.
• Orchestration across channels needs shared identity. Email is usually keyed on email address; push is keyed on device token; in-app is keyed on the SDK user/device context. If identify is inconsistent, frequency controls and suppression logic won’t behave.
• Versioning matters. When you change event schemas, keep backward compatibility for at least one app release cycle. Otherwise segments and journeys built on old properties silently stop matching new events.

Implementation Checklist

Use this to keep the rollout tight and avoid the “we shipped it but nothing matches” week that usually follows.

• Chosen a stable primary user identifier (internal customer ID) and documented it
• Installed the correct SDK packages/modules for your channels (core + push/in-app as needed)
• SDK initialized at app startup
• Anonymous events tracked before login (product view, add to cart, checkout start)
• identify implemented on login/signup and tested
• Anonymous-to-known activity merge validated in Customer.io profiles
• Push token registration + refresh implemented (if using push)
• Event naming convention + property schema documented and enforced across platforms
• QA run-through for real D2C flows (browse → cart → login → purchase)
• Journeys include purchase-based exit conditions to prevent “already bought” spam

Expert Implementation Tips

These are the operator moves that make SDK data actually usable for retention, not just “present.”

• Identify once you’re confident—then stick to it. Don’t call identify with a temporary ID and later swap to a real ID. That’s how duplicate profiles happen and why suppression/frequency caps get weird.
• Send item arrays, not just totals. For carts and orders, include an items array with product_id, variant, qty, price. That unlocks category-based recovery (“Finish your hydration bundle”) instead of generic “You left something behind.”
• Track “Removed from Cart” if you want cleaner recovery. Without it, your cart segment can include shoppers who already edited down to zero. This is a common reason cart flows feel off.
• Guard against duplicate event firing. Mobile UIs can double-fire taps. Add idempotency keys (like cart_id + timestamp bucket) or debounce logic for events that trigger journeys.
• Keep opt-in status as an attribute you trust. Push/email/SMS permissions should update attributes immediately so journeys don’t attempt channels the customer can’t receive.

Common Mistakes to Avoid

Most retention tracking problems look like “Customer.io is buggy,” but they’re usually identity and schema issues upstream.

• Using email as the primary identifier. When emails change or are missing at first session, you create fragmented profiles and lose pre-login behavior.
• Calling identify too late. If you wait until after purchase confirmation, you miss the whole pre-purchase funnel and your cart/browse recovery segments stay anonymous.
• Inconsistent event/property names across iOS and Android. One platform sends AddedToCart, the other sends Added to Cart—now your journey only triggers for half your users.
• Not validating merge behavior. Teams assume anonymous events “just attach” after login. When they don’t, cart recovery underperforms and nobody knows why.
• No purchase exit condition in recovery flows. Even with perfect tracking, you need orchestration logic so a late-arriving cart event doesn’t trigger a reminder after the customer already ordered.

Summary

If you want retention journeys to fire reliably, treat SDK packages and configuration like revenue infrastructure: install the right modules, identify users at the right moment, and standardize event schemas.

Once identity stitching and event hygiene are solid, cart recovery, repeat purchase, and reactivation become orchestration problems—not data problems.

Implement Packages Options with Propel

When teams ask us to help with SDK package/config decisions, it’s usually because they’re seeing duplicate profiles, missing cart events, or push targeting that doesn’t line up with email audiences. Working inside Customer.io, we’ll map the minimum viable event schema for retention, validate identity stitching end-to-end, and make sure your journeys have the right guardrails so the data behaves in production.

If you want to sanity-check your current implementation (or plan a clean rebuild), book a strategy call and bring one real scenario—like “mobile cart abandon after login”—so we can trace it from SDK event to segment to send.