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! |
If you haven't done so already, head to onesignal.com and setup an account. It's free!
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 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.
If you have other team members that need access to your OneSiganl account, see our Account Management page.
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.
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.
Optional
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.
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.
Requirements:
- You must have an HTTPS website.
- Your users must be subscribed to the same origin you are adding to OneSignal.
- 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.
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.
Recommended
You can import your current emails and phone numbers through the OneSignal Dashboard using a csv file or the API. More details see:
Recommended
Required for Integrations
OneSignal stores user data as a device record with a unique Player ID (OneSignal User ID) when the device:
- Web Push: Subscribes to Push Notifications
- Mobile Apps: Opens the Mobile App with OneSignal SDK
- Email shared with OneSignal. See Import Email Addresses
- SMS shared with OneSignal. See Import Phone Numbers
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.
Optional
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.
Optional
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.
Now, you have likely subscribed users and are ready to start sending messages!
- Sending Push Messages for all the details on sending push.
- Automated Messages which is how to setup drip campaigns to send messages automatically to users.
- Sending Email Messages
- In-App Messaging Overview to get the full spectrum of In-App Message Capabilities for Mobile Apps.
- Sending SMS - Learn about how to setup SMS first.
👍
Congrats 🎉
If you have come this far you have fully integrated OneSignal and are now a master!