Migrate from OneSignal to Bird Push
Move the sending workflow, customer association and receiving SDK together. Keep the app's existing platform identity and the customer's preferences, and distinguish provider IDs from actual device destinations.
Map the integration
| OneSignal concept | Bird equivalent or migration work |
|---|---|
| App ID and REST API key | Bird application configuration plus workspace/channel IDs; server sends use a Channels API AccessKey. |
| OneSignal ID / your external ID | Retain your customer ID; establish the Bird contact with a server-issued signed identity. Provider user IDs are separate. |
| Subscription ID | A OneSignal subscription ID is not a Push token. Register the installation with the Bird client and its channel. |
| headings / contents language maps | Basic Bird send uses body.list.title / body.list.text for one resolved message; use templates for your localized content workflow. |
| url, app_url, web_url, buttons and custom data | Rebuild the destination and supported actions in the Bird template or a basic single-link message; update app handlers. |
| Aliases, tags, segments and subscription preferences | Map the intended customers and rules to Bird contacts/audiences, with permission and opt-out history preserved. |
| OneSignal idempotency_key | Keep application-level send ownership and attempt reconciliation. Do not assume this field or its retry contract exists on Bird's Channels request. |
OneSignal groups subscriptions under a user and supports an external ID; its login and logout affect the association. Use its user model, subscription model and send API to inventory the current implementation. The Bird target contract is programmable Push.
Build and test the receiving path
- Create the Bird application and Push channel. Match Android's Firebase project or iOS's APNs identity/environment, and configure Bird's client SDK using platform setup.
- Register a test installation with Bird, then identify its authenticated customer using a signed identity. Do not copy OneSignal IDs into identifierValue. The documented Bird value is a gateway prefix plus a current token, under push-{channelId}.
- Recreate a representative notification: useful title/body, one authorized destination, intended language, timing and audience. Send it to one controlled device and verify the actual screen, not just provider acceptance.
- Test denied permission, token refresh, multiple devices, logout, a second account on the same device and a cold-start tap. Keep old and new handlers from displaying or opening the same notification twice.
A token export alone does not migrate SDK behavior, identity or consent. Check token provenance, matching platform credentials and a compatible receiving app before considering any server-side destination reuse. Prefer registration through the Bird client for the app version entering the new cohort. For web, the service-worker/VAPID subscription must match Bird's integration; register through the Bird Web SDK instead of treating a OneSignal subscription ID as a transferable browser token.
OneSignal's logout semantics do not define Bird's. In particular, a local Bird identity reset does not detach a browser's existing remote Push identifier. Follow the Bird installation cleanup sequence before associating the shared device with another customer.
Switch traffic and reconcile
Keep a migration ledger with customer/installation, receiving app version, registration status, notification preference and current sending owner. Choose a bounded cohort with a working Bird registration. Route each business event through one sender and suppress the corresponding old campaign or trigger for that cohort.
Record original event and message IDs, including uncertain outcomes. Do not replay an entire OneSignal campaign into Bird merely because some receipts are missing. Reconcile its attempts and the customer's current state first. Keep business-event deduplication in your application; Bird's request reference is correlation, not a substitute for a documented idempotency contract.
Compare send failures, device presentation, tap routing and application outcomes using the same definitions. Retain the old configuration for rollback until the cohort is stable. Rollback changes the owner of future events; it cannot undo delivered notifications. Remove obsolete SDK handlers, subscriptions and credentials only after old app versions and outstanding attempts have been accounted for.
References and next steps
- OneSignal users, subscriptions and notification request.
- First Bird notification, device lifecycle, deep links and troubleshooting.
- Compare Bird and OneSignal or all Push resources.
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.