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.
|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.|
- Importing Web Push Subscribers
- Importing Mobile App Subscribers
- Importing Email Addresses
- Import Phone Numbers
|Step 3. Connect User Data to OneSignal||Understanding OneSignal Device Records data.|
- External User Ids.
- Connect with your Database, DMP, & CRM Integration.
|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:|
- Sending Push Messages
- Automated Messages
- Sending Email Messages
- In-App Messaging Overview
- Send SMS
SDK Implementation is recommended. Our SDKs are open source 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 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.
See OneSignal's Custom Push Payload for more details.
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.|
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 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.
- 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 update and open the app with the OneSignal SDK active will automatically be added to OneSignal and will keep their current subscription status.
iOS subscribers can be imported and start getting push immediately. 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.
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 number 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 the Database, DMP, & CRM Integration 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.
If importing this data from the API, you can map the User IDs to
external_user_id: "123" and data attributes as
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.
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 External User Ids 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.
Custom User data can be stored in OneSignal as Data Tags which are
key : value pairs of string or number data.
Helpful setup guides:
- Data Tags Overview - Overview of how data tags work.
- Message Personalization and Time Operators - Add user details to a message or track events based on time.
- Example code and common use case setup in Use Cases & Best Practices.
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. Send test messages by Finding your Devices & Set Test Users.
- Automated Messages which is how to setup drip campaigns to send messages automatically to users.
- Sending Email Messages - Make sure you are setup with our Email Overview first.
- 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.
If you have come this far you have fully integrated OneSignal and are now a master!
Updated over 1 year ago