Onboarding With OneSignal

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

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

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

Quick Reference Details
Step 1. Setup OneSignal SDK Recommended: Use the SDK Integration.
- Discussion of API-only integration
Step 2. Migrating Current Users to OneSignal Optional: Import current users into OneSignal. Requires having previous subscribers.
Step 3. Identifying Users Recommended: Understanding OneSignal Device Record data.
- External User Ids
Required for integrations with your database or DMP (Mixpanel, Hubspot, Segment, Amplitude, etc).
Step 4. Send OneSignal Event Data & User Attributes Optional: Add Custom User Attributes and Event data to target users with push and customize push messages.
Step 5. Outcomes Optional: OneSignal's Advance Analytics to get more insight into your messaging campaigns.
Step 6. Sending Messages Send messages to users!
Step 1. Setup OneSignal SDK

If you haven't done so already, head to onesignal.com and setup an account. It's free!

Push & In-App Messaging

SDK Implementation is recommended for Push and required for In-App Messages.

Our SDKs are open source and easy to setup. On average, customers get setup and send their first push in under 30 minutes. Follow the steps in our Quickstart guides to get started:

Email & SMS

Email and SMS integrations do not require the OneSignal SDK. However, the SDKs do provide methods for passing in emails and phone numbers into your OneSignal app.

Add Team to OneSignal

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

Server API Integrations

OneSignal provides APIs for creating and updating device records along with sending messages. For example, you can create and update device records with the Add a device and Edit device APIs. Server API-only integrations are not recommended if you are using Push Notifications and unavailable for In-App Messaging.

Note on the OS Push Payload

Push notifications have several different requirements that our SDK handles for you. For example, the APNS push payload has a standardized format but Android does not. Setting up both would need additional dev work to handle notifications client side. OneSignal's Push Payload contains a "custom" key with a nested "i" value, which must be included for our SDK to handle the push notification. See OneSignal's Custom Push Payload here and our article on Build vs Buy for more details.

Step 2. Migrating Current Users to OneSignal


Once the OneSignal SDK is integrated, your users will automatically become available in your OneSignal dashboard when they update and open your mobile app or return to your website (certain web requirements apply). Previously subscribed devices will stay subscribed and can be sent messages. Also, subscribed iOS and web users will not be shown the subscription prompt again.

The OneSignal SDK collects certain user data automatically. For custom user data/attributes/properties these can be stored as Data Tags which are Key: Value pairs of string or number data. Data should be stored as arrays or objects in OneSignal.


Data Required for Push Notifications

You cannot directly import push subscribers without a push token identifier. The 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

Due to the way Browsers have set up Web Push, you cannot directly import subscriber data from a different push provider into OneSignal. However, if your site meets the below requirements, current subscribers will be automatically moved 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 website.
  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 send push from the old provider until you are ready to fully move to OneSignal.

Importing Mobile App Subscribers

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

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

iOS subscribers can be imported using our API and start getting push immediately. However, features like monitoring notification click rate won't work for devices without the OneSignal SDK active.

Android subscribers can be imported using our API. 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.

Importing Emails & Phone Numbers

You can import your current emails and phone numbers through the OneSignal Dashboard using a csv file or the API. More details see:

Step 3. Identifying Users

Required for Integrations

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 an External User Id 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.

If you are integrating with your own database or one of our partners like Mixpanel, Hubspot, Amplitude or Segment, please follow the setup guides listed in our Integrations Page.

Step 4. Send OneSignal Event Data & User Attributes


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

Tags can be used for Segmentation and Message Personalization.

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!