OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Onboarding With OneSignal

Guide on moving to OneSignal: Migration steps, importing devices and getting started quickly.

Moving to OneSignal? Good choice! We are are happy to have you!

Whether you are moving millions of users or just getting started, this checklist walks through getting setup as fast as possible.

Quick Reference


Step 1. Setup OneSignal

Recommended: Use the SDK Integration.

  • Discussion of API-only integration

Step 2. Migrating Users to OneSignal

Optional, requires having previous subscribers.

Step 3. Connect User Data to OneSignal

Understanding OneSignal Device Records data.

Step 4. Send OneSignal Event Data & User Attributes

Add Custom User Attributes and Event data to target users with push and customize push messages.

Step 5. Outcomes

OneSignal's Advance Analytics to get more insight into your messaging campaigns.

Step 6. Sending Messages

Send messages to users! Including:

Step 1. Setup OneSignal

SDK Implementation is recommended. Our SDKs are open source, very lightweight, and easy to setup. On average, customers get setup and send their first push in under 30 minutes.

If you have other team members that need access to your account, see our Account Management page.


Next Steps After Adding The SDK

If migrating subscribers to OneSignal from another provider, continue to Step 2 Migrating Users to OneSignal.

If you are integrated with a database or 3rd party data platform see Step 3 Connect User Data to OneSignal.

To collect custom user data in OneSignal, see Step 4 Send OneSignal Event Data & User Attributes.

To just start sending messages: Step 6 Sending Messages.

API Only Integrations (Not Recommended)

API-only integrations are generally not recommended. Each platform (Android, iOS, Web) has different push notification requirements. For example, iOS has a standardized APNS push payload but Android has a non-standard push payload and Web Push requires Service Workers; both of which would need additional dev work to handle notifications client side.

Without our SDK, you will need to setup client-side functionality with native code for subscriber authentication, the displaying of the push message, and parsing our notification payload (Android and Web). Our SDKs provide a lot of functionality that will cutdown your development time.

If you want to continue pursuing an API-only integration, you can use the Add a device endpoint to add devices to OneSignal and the Edit device endpoint for updating device records already created.

Handling Custom Notification Payloads

The OSNotificationPayload Object contains a β€œcustom” key with a nested β€œi” value like this: β€œcustom”: { β€œi”: β€œβ€}.

On Android, if the notification payload received does not contain this, our SDK will not process the notification. However, if you have another SDK, there is no guarantee it will not process our Notifications.

On iOS, because Apple has a standard payload it will show all notification sent to the device. So if you send a push from your old platform to a device, do not send the same notification from OneSignal or the user will get it twice.

For iOS Click Handlers, depending on how you handle notification opens you might have to add a check for β€œcustom”: { β€œi”: β€œβ€} data (or if you have your own format, we recommend checking for yours instead) if you need to handle the notification sent from OneSignal differently than notifications sent from other provider.

Step 2. Migrating Users to OneSignal

Once the OneSignal SDK is integrated, your users will automatically show in your OneSignal Audience page upon users updating and opening the App or returning to the Website.

Previously subscribed devices will not be shown a prompt, they will continue to be subscribed within OneSignal and can get push immediately.


Data Required for Push Notifications

You cannot directly import devices without the device having a push token associated with the record. A Push Token is generated through the website or mobile app when the user subscribes.

Phone number, email address, IP address are not enough information to target a user for push.



Importing Web Push Subscribers

Detailed steps to automatically and silently move subscribers to OneSignal.

Importing Mobile Push Subscribers

What to expect when transferring mobile app subscribers from another provider.

Importing Email Addresses

OneSignal supports email integrations with Sendgrid, Mandrill, and Mailgun.

Importing Phone Numbers

You can use our CSV Upload functionality to import SMS subscribers to OneSignal. You will need a Twilio account to send SMS.

Importing Web Push Subscribers

Due to the way Browsers have setup Web Push, you cannot directly migrate subscriber data from a different push provider into OneSignal. However, if your site meets the below requirements, then there is a way to automatically resubscribe users into OneSignal when they return to the site. No prompt will be shown and they can get push immediately upon return. They should also stop getting push from the previous provider.


  1. You must have an HTTPS site
  2. Your users must be subscribed to the same origin you are adding to OneSignal.
  3. You must be able to add Service Worker files to your server (cannot select "My site is not fully https" in the OneSignal dashboard).

If your site does not meet these requirements, users will need to resubscribe to the site. You can continue to follow these steps and send push from the old provider until you are ready to fully move to OneSignal. Eventually devices will stop getting push from the previous provider if you follow the steps below and once the previous Service Worker files are replaced with the ones we provide.


  1. Remove all your previous Push Provider's code from your site. Including their service workers.
  2. Follow our Web Push Setup.
  3. Check your Service Workers. If you placed your previous push provider's service workers in the root of your site (e.g then simply remove those service workers and use the OneSignalSDKWorker.js and OneSignalSDKUpdaterWorker.js files (shown in setup).

If you added your other service workers to a subdirectory (not the root) you will need to unregister your previous service workers. For example, if you added your service worker to then you will need to unregister your service worker before the user can subscribe to OneSignal, use this code to unregister your service worker:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistration ('/subdirectory/js/service-worker.js'). then (function (registration) {
    if (registration) {

Make sure to change /subdirectory/js/service-worker.js to the actual path of your service workers are found.

  1. Test your site to make sure you can subscribe and show up in the OneSignal Dashboard. In the browser's debugger console, check the Application > Service Workers and make sure no other service workers are registered or trying to register.

See Troubleshooting Web Push if you are having issues.

Then you can continue to send push notifications from your previous push provider to current subscribers. Upon revisiting your site, your subscribed users will now show up in your OneSignal Dashboard and the previous Service Worker should be removed from the subscribers browser and replaced with the OneSignal Service Worker.

At that point, the subscriber will not be able to get notifications from the previous provider and should show as unsubscribed in the previous provider's system. No duplicate notifications should occur.

Importing Mobile App Subscribers

Before migrating, we recommend releasing your app with the OneSignal SDK. Any user that update and open the app with the OneSignal SDK active will automatically be added within OneSignal and will keep their current subscription status.

iOS subscribers can be imported. However, features like monitoring notification click rate wont work for devices without the OneSignal SDK active.

Android subscribers can be imported. However, they will not be able to receive notifications until they update to a version of your app with the OneSignal SDK. Therefore it's usually not beneficial to import them since they would get added to OneSignal automatically after they updated and opened your app anyway.

You can import your current subscribers using the API Add a device POST Endpoint.

Importing Custom User Attributes To OneSignal

If you are moving to OneSignal from another provider that has custom data/attributes about users, that data can be stored in OneSignal as Data Tags which are Key: Value pairs of string or integer data. Data cannot be stored as arrays or objects in OneSignal.

If you track your own User IDs (like in your CRM or Database), you can add these to OneSignal user records as external_user_id's. See our Internal Database, DMP, & CRM Guide for more details.


Only Import Necessary Data

OneSignal automatically collects common user data which you can view here in Data Collected by the OneSignal SDK.

For custom user data, it is recommended to only import data needed for sending messages.

List Import Option

If you map User IDs from your other provider or database as external_user_ids then you can use the Importing User Attributes option.

API Import Option

If importing this data from the API, you can map the User IDs to external_user_id: "123" and data attributes as tags: {"tag_key_1":"tag_value_1","tag_key_2":"tag_value_2"}.

SDK Import Option

If using our SDK, you can add the external_user_id with our setExternalUserId method upon login to the app/site.

For data tags, use our Tagging Methods in areas that capture the data needed for push.

Step 3. Connect User Data to OneSignal

Recommended Step

OneSignal stores user data as a device record with a unique Player ID (OneSignal User ID) when the device:

For example, a User that subscribes to Push Notifications on your website and downloads your iOS mobile app will have 2 OneSignal Player ID records. If you incorporate Email, then that single User will have 3 records: 2 Push Records (web and iOS) + 1 Email Record.

To associate multiple Player ID records together, use the SDK setExternalUserId method to map your Database/DMP/CRM User ID to the current Player ID. The "external_user_id" can be anything like an email, username, or Database User ID.

Similarly, the setEmail method will associate the current Player ID Push record with a newly created or current Email record in the system.


Setup Recommendation

We recommend calling setExternalUserId and setEmail each time the user gets authenticated (logs in or opens and verified) to your site or mobile app to make sure your custom User ID and Email is associated with the OneSignal record.

See Database, DMP, & CRM Integration for details on integration.

Once this mapping is complete, any data changes through our SDK (update tags or "last active") will update the current active Player IDs (Push and Email) records. It will not update all associated records.

For example, the user logs into the Website, setExternalUserId and setEmail are called. Then later sendTag method is called. This will update the tags for the Web and Email Player ID records but not the iOS Player ID record even if they External User ID is the same across all 3 Player ID records.

The OneSignal Server side API Edit tags with external user id endpoint can associated tags across multiple Device Records with the same External User ID.

You can disassociate External User IDs with the removeExternalUserId method (removes External User ID from the current Player ID record) and Emails with logoutEmail method respectively (keeps email record but removes the connection with the current Player ID).

Step 4. Send OneSignal Event Data & User Attributes

Recommended Step

Custom User data can be stored in OneSignal as Data Tags which are key : value pairs of string data.

Tags can be used for Segmentation and Message Personalization.

Helpful setup guides:

Step 5. Outcomes

Outcomes are OneSignal's advanced analytics that lets you track actions users take after clicking or receiving messages.

For instance, tracking "clicks" is nice, but setting Outcomes can show you how much revenue was brought in from a push. Also track user behavior after entering the app/site, like did they read/share/update/interact with a post or another user. Other tracking includes click stats like country or language or app version.

Step 6. Sending Messages

Now, you have likely subscribed users and are ready to start sending messages!


Congrats πŸŽ‰

If you have come this far you have fully integrated OneSignal and are now a master!

Updated about a month ago

Onboarding With OneSignal

Guide on moving to OneSignal: Migration steps, importing devices and getting started quickly.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.