Whether you are migrating to OneSignal or just getting started, we're happy to have you! This checklist walks through getting set up as fast as possible. If you haven't done so already, head to onesignal.com to set up your account.
Add your Team!
If you have other team members that need access to your OneSignal instance, see our Account Management page to invite them.
Required for Push, In-App Messages, and Live Activities; Recommended for SMS and Email
Follow the steps in our Quickstart guides to get started integrating our Client-side SDKs:
As you continue integrating OneSignal into your application, you may find it helpful to use one of our Backend Server-side SDKs to simplify and orchestrate API calls.
OneSignal provides the Create user, Create subscription, Update user, and Update subscription APIs for creating and updating user and subscription data along with the Create notification API sending push notifications, email, and SMS messages. The OneSignal SDK is required if you plan to use the In-App Messaging functionality.
Server API-only integrations are possible but not recommended because push notifications have several different requirements that our SDK handles for you, including:
- obtaining push tokens across Android, iOS, Huawei, and Web Browsers
- verifying subscription status, prompting, and opting-in users
- displaying the notification and handling the payload
For example, the APNS push payload has a standardized format but FCM 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 when sent through our system. Our SDK checks this value to handle the push notification. See OneSignal's Custom Push Payload here and our article on Build vs Buy for more details.
Recommended; Required for Integrations
OneSignal stores user data under a unique OneSignal ID and the channels a user is subscribed to under a Subscription ID. You can identify your user within OneSignal by setting an External ID or custom aliases.
After integrating OneSignal's Mobile and/or Web SDKs into your application, you will want to start collecting email addresses and phone numbers to send emails and SMS/MMS text messages. Follow these guides to setup the channels and your application to collect new emails and phone numbers. You can import your current users in the next step.
Custom user properties and event data can be stored in OneSignal as Data Tags which are
key : value pairs of string or number data.
Tags will be managed at a user level and can be accessed across all subscriptions associated with a OneSignal ID. Tags can be used for Segmentation and Message Personalization.
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, they will not be asked to opt-in to messages again, and can be sent messages.
You can import your current emails and phone numbers through the OneSignal Dashboard using a csv file or the API. More details see:
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.
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.
- Remove the previous Web Push SDK from your site. Only use the OneSignal Web Push SDK. See Web Quickstart.
- You must have an HTTPS website and use the same origin in which your users are currently subscribed.
- You must be able to upload Service Worker files to your server. See OneSignal Service Worker for details on migration.
If your site does not meet these requirements or you are changing your site origin (like removing/adding www), 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.
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 Create user API.
iOS subscribers can be imported using our API and start getting push immediately. However, features like tracking notification click rate won't work for devices without the OneSignal SDK active.
Android, Amazon, Huawei 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.
OneSignal can integrate with any platform.
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.
If you have other team members that need access to your OneSignal account or want to update billing, apps or org data.
Now, you have likely subscribed users and are ready to start sending messages!
- Journeys will enable you to automate message sequences and optimize user engagement.
- Sending Push Messages for all the details on sending push.
- Sending Email Messages
- In-App Messaging Overview to get the full spectrum of In-App Message Capabilities for Mobile Apps.
- Sending SMS
If you have come this far you have fully integrated OneSignal!
Updated 2 months ago