OneSignal to Braze Migration Guide

OneSignal is where you start with push notifications. Braze is where you go when push notifications are no longer the whole story.

OneSignal is one of the most widely adopted notification delivery tools in the market — accessible, developer-friendly, and effective at the single problem it was built to solve: sending push notifications. Teams that have built meaningful mobile engagement programs on OneSignal eventually encounter the same ceiling: they need email coordinated with push, in-app messaging triggered by the same behavioral events, SMS in the same Canvas, and personalization that goes beyond static segment tags.

That ceiling is where the migration to Braze begins.

At Propel, we've managed OneSignal-to-Braze migrations for consumer apps, subscription businesses, and DTC brands that started with notifications and built their way into a lifecycle program their notification tool wasn't designed to support. The migration is one of the more structurally clean transitions in the enterprise engagement space — but it comes with specific gotchas around push registration that need to be handled correctly.

TL;DR

• OneSignal is a notification delivery tool. Braze is a customer engagement platform. The migration is not a platform upgrade in kind — it's a category upgrade. You're moving from a notification sender to a lifecycle orchestration engine.
• OneSignal has no workflow builder equivalent to Canvas Flow. OneSignal's "Journeys" feature exists in some plans but is limited compared to Braze's Canvas Flow in cross-channel depth and orchestration logic. Every notification sequence must be rebuilt as a Canvas.
• Push registration doesn't transfer. OneSignal holds device push tokens that cannot be moved to Braze. When the Braze SDK initializes on a device, it requests a fresh token from APNs/FCM. For users who have granted push permission, this is seamless. For users who haven't, no platform can recover it.
• The migration unlocks email, in-app messaging, SMS, and Content Cards — all coordinated in Canvas Flow with the same behavioral event stream driving all channels.
• Propel is a certified Braze partner with consumer app and subscription brand migration experience.

Why Teams Move From OneSignal to Braze

Email in the same event stream. OneSignal is a notification delivery tool — it doesn't have native email capabilities at the lifecycle level. Teams running OneSignal are almost always running a separate email tool alongside it, with two systems, two segment definitions, two frequency rules, and two attribution dashboards for a single user's lifecycle. Braze unifies this. A Canvas that starts with a push notification, checks whether the user engaged, and escalates to email or SMS based on non-response — built in a single workflow, triggered by a single event stream — is the omnichannel orchestration that OneSignal's architecture can't produce.

In-app messaging. OneSignal supports in-app messages in some configurations, but they're not deeply integrated into a cross-channel workflow logic. Braze's in-app messaging is native to Canvas Flow — the same event that triggers a push can trigger an in-app message in the next step, or conditionally, based on whether the user opened the push. For customer retention for lifestyle apps and ecommerce apps, in-app messaging is often the highest-engagement touchpoint in the lifecycle program.

Connected Content. OneSignal's push personalization is tag-based — you insert user data tags into notification content. Braze's Connected Content makes a live API call at send time to pull dynamic data from any external endpoint. For apps that need to personalize push notifications with real-time product data, live recommendations, or current account state, Connected Content is the capability gap that makes the migration worth the investment.

Data infrastructure. Braze Currents streams every engagement event to your data warehouse in real time. Combined with cloud data ingestion and a broad native integration ecosystem, Braze gives lifecycle and analytics teams the data infrastructure that behavioral segmentation at scale requires. OneSignal's data export capabilities are functional for notification analytics but not built for lifecycle attribution at the warehouse level.

Predictive capabilities. Braze's Predictive Churn and Predictive Purchases models run natively on Custom Event data. For subscription businesses trying to identify users who are about to churn and act before they do, Braze's native predictive features eliminate the need for a separate ML pipeline.

One subscription brand we migrated had been running OneSignal for push and a separate ESP for email. Their push and email programs were completely disconnected — different segment logic, different frequency rules, no shared attribution, and frequent cases of a user receiving both a push notification and an email with the same message within an hour. The Braze migration consolidated both channels into Canvas Flow. Within 60 days of go-live, the frequency collision rate dropped to near-zero, email-attributed revenue increased as campaigns became behaviorally triggered rather than batch-scheduled, and push opt-out rates decreased as send timing improved with Intelligent Timing calibration.

The Architecture Difference: OneSignal vs. Braze

OneSignal's model: Device-centric and notification-first. Users are identified by Player IDs (device-level identifiers) or External User IDs. Segments are defined by tags, data filters, or location. Notifications are sent to segments or individual users. The workflow logic is notification-centric — sequences of notifications, not cross-channel lifecycle orchestration.

Braze's model: Profile-centric and channel-agnostic. Every user has a unified profile with Custom Attributes and Custom Events. Canvases trigger off Custom Events from any source and can send any combination of email, push, in-app messaging, SMS, and Content Cards from a single workflow. The data model was designed for lifecycle orchestration, not notification delivery — which changes both what the platform can do and how it needs to be implemented.

The migration consequence: OneSignal's External User IDs map to Braze's external_id. OneSignal's device tags — used for segmentation — map to Braze Custom Attributes. OneSignal's notification templates must be rebuilt in Braze's Canvas push step composer. Push device tokens do not transfer and re-register via SDK initialization. Every notification sequence must be rebuilt as a Braze Canvas.

What Transfers and What Doesn't

Transfers With Mapping ✅

External User IDs → Braze external_id. If your OneSignal implementation uses External User IDs (the recommended approach for identified users), these map directly to Braze's external_id. Anonymous Player IDs can be handled via Braze's user alias system for pre-login users.

User data tags → Custom Attributes. OneSignal's data tags — used for segmentation and personalization — map to Braze Custom Attributes. Document every tag in active use across segments and notification templates. Tags not in active use don't need to migrate.

Email unsubscribes and SMS opt-outs. These transfer and move first. Map to Braze's email_subscribe: unsubscribed and SMS Subscription Group opt-out status respectively.

Push opt-in status. Push opt-in does not transfer as data — it re-establishes via SDK initialization when the Braze SDK reads the device's OS-level push permission. See the Push Registration section below.

Must Be Rebuilt 🔄

All notification sequences become Canvases. OneSignal's Journeys (where available) and any manual notification sequences must be rebuilt as Braze Canvases. For the first time, these sequences can include email, in-app messaging, and SMS in the same workflow — which is the migration's primary capability unlock. Start with the Braze onboarding Canvas template for your highest-volume onboarding sequence.

SDK instrumentation. The OneSignal SDK must be replaced with the Braze SDK. This is a planned app release. Every Custom Event in your Braze schema must be validated as firing correctly before any Canvas is built. This is the core work of our events and attributes architecture pre-migration process.

Segments. OneSignal's tag-based segments must be recreated in Braze's builder using Custom Attributes and event filters. The lifecycle stage segmentation playbook provides the framework for rebuilding segment logic in Braze's model.

Notification templates. OneSignal's push notification templates must be rebuilt in Braze's push composer. Personalization tags must be rewritten in Braze's Liquid format. Run the pre-send email QA checklist on every rebuilt template.

Newly Available in Braze

Email, in-app messaging, and SMS — these are channels your lifecycle program didn't have in OneSignal at the Canvas orchestration level. The migration is not just a platform swap; it's a channel expansion. Building your first cross-channel Canvas — push and email and in-app messaging coordinated by a single behavioral event — is the moment the migration delivers on its promise.

Push Registration: The Critical Transition Detail

OneSignal holds APNs and FCM device tokens that cannot be exported and re-registered in Braze. This is the most misunderstood aspect of any notification-platform migration.

The correct mental model: push notification permission is granted by the user to the app, at the OS level. OneSignal held the device token that represented that permission. When you release an app version with the Braze SDK, Braze requests a fresh device token from APNs/FCM at SDK initialization. For users who have previously granted push permission, the OS issues a new token to Braze automatically and silently. The user's experience is unchanged — they continue receiving push notifications, now via Braze.

For users who have denied push permission, that denial persists. No platform migration can recover a permission that was explicitly denied. The migration is not an opportunity to restore denied permissions — it's an opportunity to ensure that users who granted permission continue to receive notifications without interruption.

The practical steps: release the Braze SDK in your app. Braze SDK initialization triggers a fresh device token registration for opted-in users. Monitor your Braze push opt-in count in the first 48 hours post-release — it should match or closely approximate your OneSignal opted-in count. A significant gap indicates an SDK initialization issue, not permission loss.

For subscription brands where push is a primary retention channel, getting this transition right is the most consequential technical moment in the migration.

Migration Checklist: OneSignal to Braze

Pre-Migration Audit

• Document all active notification sequences, automated messages, and Journeys — trigger, channel, 30-day performance.
• Document all data tags in active use — map to Braze Custom Attribute data types.
• Map OneSignal event schema to Braze Custom Event schema if using data events.
• Assess cross-channel expansion scope — determine which email and in-app capabilities will go live at migration versus later.
• Coordinate SDK release timeline with mobile engineering.

Data Migration

• Export email unsubscribes — import to Braze as email_subscribe: unsubscribed.
• Export SMS opt-outs — import to Braze SMS Subscription Groups.
• Export active users with all data tags — map to Braze Custom Attributes.
• Segment import into engagement tiers before any Canvas is activated.
• Push opt-in re-establishes via SDK initialization — do not attempt to import OneSignal push tokens.

Technical Setup

• Verify sending domain in Braze for email channel — DKIM, SPF, DMARC. Reference email deliverability channel health standards.
• Integrate Braze SDK in iOS and Android — validate every Custom Event and property against schema.
• Configure APNs and FCM credentials in Braze.
• Configure Braze Subscription Groups for email and SMS.
• Set up Braze Currents for data warehouse or analytics integration.

Canvas Rebuild and Go-Live

• Rebuild all notification sequences as Braze Canvases — expand to include email and in-app messaging steps where appropriate.
• Rebuild all push notification templates in Braze's composer.
• Run end-to-end Canvas QA including push send validation with test device tokens.
• Monitor push opt-in count in Braze within 48 hours of SDK release — validate against OneSignal baseline.
• Deactivate OneSignal segments and automated messages as Braze Canvases go live.
• Execute email deliverability warm-up over 4–6 weeks if email is being activated alongside push.

Building Your First Cross-Channel Canvas

The most tangible demonstration of what the Braze migration unlocks is the first Canvas that does something OneSignal couldn't do: coordinate push, email, and in-app messaging in a single behavioral workflow.

A practical first Canvas: your re-engagement sequence. In OneSignal, this might have been a push notification sent 7 days after inactivity, then another at 14 days. In Braze Canvas Flow, the same sequence becomes:

• Day 7 of inactivity: Push notification — "We miss you." Check if opened within 24 hours.
• If not opened, Day 8: Email — behavioral re-engagement with personalized content from Connected Content.
• If email opened but no app session started within 48 hours: In-app message on next app launch — direct prompt to the feature they last used.
• Day 21 of continued inactivity: Final push with time-limited offer. Exit if not engaged.

This Canvas runs entirely on a single last_session Custom Attribute and a single app_session_started Custom Event. It coordinates three channels in a single workflow. It responds to user behavior at each step, not just to time intervals. And it can be built, tested, and launched in a week once your SDK events are validated.

This is how to win back dormant users at the infrastructure level — not just a new message, but a new system that responds to behavior rather than scheduling.

Stakeholder Expectations

Lifecycle team: Budget 8–12 weeks for a typical OneSignal migration, including the cross-channel Canvas build for channels you're activating for the first time. The SDK validation and Canvas rebuild are the primary time investments. Our campaign analytics and performance insights service maintains visibility through the transition.

Engineering team: SDK migration requires a planned app release. Budget 2–3 weeks of engineering time for SDK instrumentation and event validation. The push token transition is handled automatically by the SDK — it doesn't require engineering intervention beyond the SDK release itself.

Data and analytics teams: Currents integration should be set up before the first Canvas goes live. Involve your data team in Custom Attribute and event schema design from the start. Our events and attributes architecture service manages the specification.

Leadership: If email is being activated alongside push as part of the migration, plan for the email deliverability warm-up period — 4–6 weeks where email send volume is restricted to your most engaged segment. Brief leadership before the first month shows a send volume reduction. Use the customer retention impact calculator to set the 90-day revenue baseline.

Why Propel for Your OneSignal to Braze Migration

Propel is a certified Braze partner with consumer app and subscription brand migration experience. Our migration framework covers the full program — SDK transition planning, push registration management, cross-channel Canvas build, email deliverability warm-up, Currents integration, and the lifecycle strategy review that every Canvas rebuild should include.

Talk to a Propel operator about your OneSignal to Braze migration.