Migrate to Carillon

We recommend moving one app at a time. Existing APNs and FCM tokens depend on the same Apple app identity and Firebase project, so these need to stay the same during migration. Importing tokens does not install the Carillon SDK, transfer notification permission, or reproduce another provider's campaigns.

Choose your provider

Move from OneSignal: export subscriptions, convert the CSV, import devices, and move sending as app updates reach your users.

For another provider, use the CSV import format. You should import only mobile push subscriptions that are currently eligible to receive messages.

Plan the transition

We recommend the following sequence for a gradual rollout:

1. Recreate credentials, targeting rules and notification content in Carillon.
2. Import a small test audience and verify a notification on a real device.
3. Release an app update with the Carillon SDK alongside your existing integration.
4. Assign each device to one sending service. Confirm its new registration before disabling its old subscription.
5. Repeat imports to add new tokens while older versions remain in use.
6. Remove the old SDK in a later release, after defining what happens to users who have not updated.

The same device can exist in both databases. That is expected; sending the same message through both services to that device is not deduplicated by Carillon. Its idempotency and deduplication keys apply only to Carillon requests.

Know what an import preserves

Within one Carillon app, an existing token is skipped. Its identifiers, tags, preferences and SDK updates are not overwritten. New tokens create new devices; a changed token is not merged by external_id.

Repeated imports add devices; they do not synchronize changed fields, remove missing rows or propagate later opt-outs. You should account for preference changes separately during the transition, including on devices still using the old app version.

Read the import format and report.