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

Users & Subscribers Guide

Managing and understanding your users in the OneSignal Dashboard.

Once you setup OneSignal on your Website and/or Mobile App you should start to see both Subscribed Users and Total Users appear in your dashboard.

Subscribed Users is the amount of devices in which you can send messages.
Total Users is a combination of Subscribed + Unsubscribed devices.

A "user" record is created and subscribed in the following ways:

  • Mobile Apps: a device downloads and opens your app, a user record is created. Android devices get subscribed automatically upon open. iOS devices generally need to opt-in to push.
  • Websites: a device tied to a browser profile visits the site and opts-in through the Native Browser Prompt.
  • Email: an email address can be sent to OneSignal through our API or Dashboard. See our Email Overview.

Once the User record gets created, an unique player_id is automatically assigned to the device. You can also set your own custom user ids (external_user_id) to devices for targeting as well. See Internal Database, DMP, & CRM for more details.


Managing Users in OneSignal

OneSignal automatically handles user tracking and subscription updates through the SDK. You can view user data through the Dashboard or Export User Data through the dashboard or API.

If you have an analytics tool, see our Analytics Integration Guides for more details on setting this up.

Subscription Process

Web Push Subscribers and iOS Mobile App Subscribers must opt-in to subscribe. See our Prompting Guide for more details on getting permission.

Android Mobile App Subscribers are opted-in when they open the app for the first time.

OneSignal's SDKs provide Permission Observer and Subscription Observer methods to detect these events client side.

Detecting Unsubscribes

Devices get unsubscribed when they:

Any subscribed device that unsubscribes will be detected and marked in OneSignal automatically when they:

  1. Interact with the OneSignal SDK (increasing Revoked Count). You can capture this event with our Subscription Observer methods and send to your Database.

  2. After you send 2 notifications to the unsubscribed device on Android Mobile Apps and Web. For iOS, this may take a week for Apple to update the subscription record. More details below.

If you target devices directly via the API using include_player_ids or include_external_user_ids parameters we also provide the unsubscribed devices as "invalid_player_ids" or "invalid_external_user_ids" callback results which you can process in your Internal Database, DMP, & CRM.

🚧

iOS Unsubscribe Detection

Apple changed the way it reports unsubscribe events on iOS apps.

In the past, they would report the unsubscribed device upon the 2nd notification. They stopped doing this for privacy reasons. Apple intentionally does not want token invalidation to be used as a method to detect app uninstall.

Some details provided by Apple can be found here: https://forums.developer.apple.com/thread/116445

Currently if a device unsubscribes and opens the app, we detect this right away through our SDK. However if the device uninstalls the app or unsubscribes and does not open the app, it may take several weeks for Apple to report the device unsubscribe event.

If you need to remove older devices, you can delete them using our dashboard or API.

OneSignal Dashboard User Management

The All Users page is where you can view all user records of your app/website. Use this page to:

The Segments page is where you can group devices by data filters to target with messages.


Player ID

The OneSignal Player ID is a UUID (Unique Universal Identifier) that OneSignal creates per device per OneSignal App ID. The format is lowercase letters and numbers 8 characters-4 characters-4 characters-4 characters-12 characters like b3aaabc2-9a47-4647-adda-3e4583a2d19e.

The Player ID is generated based on the:

A common practice is to tie the OneSignal Player ID with your Database ID (we call External User Id). See our Internal Database, DMP, & CRM Integration Guide for more on this setup.

When does the OneSignal Player ID change?

OneSignal makes a best effort to keep the same Player ID on all devices that are assigned. Some circumstances that may cause it to change:

Web Push - When the user clears their cookie data for your site.

Android - If the user has opted out of the Google Advertising ID, uninstalls the app and re-installs.

iOS - If the user does not have any other apps installed that have your IFV (identifierForVendor), then uninstalling your app and re-installing it, will give them a new Player ID.

The IFV is used to keep the ID the same after a full re-install, but only if the user has another one of your apps installed.

Finding Player IDs

Please see Finding Users


External User IDs

external_user_id is used to map your unique database User ID's to the OneSignal player_id device record. This could be any unique identifier like Firebase User ID, CRM User ID, or even email if you choose.

Multiple device records in OneSignal can have the same external_user_id but will each have a unique player_id. For example, a user subscribed to your website, android mobile app and iOS mobile app will have 3 different player_id records, but you can map these devices to your database via the same external_user_id.

Our SDKs support a setExternalUserId method which you can call as soon as the user logs into your website and/or mobile apps to set their User Id.

More details in our Internal Database, DMP, & CRM.

Further, you can prevent certain platforms from getting a push if they have the same external_user_id. For example, if you want to send a notification to web-only subscribers via the external_user_id, you can target them with the include_external_user_ids API Targeting Parameter and isAnyWeb API Platform Filter.


FAQ

Managing Multiple Users On One Device

To manage multiple users that share a device, you will need to detect when User A is on the device and only send them their notifications when they are on the device, otherwise User B will get them.

Method A: External User ID

One way to handle this is to call the setExternalUserId method when each user signs in to the app, then you can target them by the external_user_id using the API include_external_user_ids parameter.

Once they log out of the app, you can remove the external_user_id with removeExternalUserId method.

This means if User A logs in and you call setExternalUserId("user_a") then any messages sent directly to user_b with include_external_user_ids will not be shown on the device until User A logs out, removeExternalUserId is called and User B logs in.

Method B: CRM or Database

The other option is to store on your server the Player IDs of the devices the user is currently logged in with, and then use our API to send notifications using the "include_player_ids" API targeting parameter.

Please see Internal Database & CRM.

You will need to detect when User A and User B are logged in/out and send the correct message accordingly.

Managing One User On Multiple Devices

Each user that accesses your site or app from a different device or browser profile will get a new and unique OneSignal Player ID.

You can ensure that you are targeting the same user across different devices in 3 ways:

1 - Add Data Tags to the user with some identifier, like their email or username.
2 - Use the setExternalUserId method to add your unique external_user_ids to the device
3 - Track the OneSignal player ids for each device on your own database. More details in Internal Database & CRM to keep track of Player IDs or External User Ids.

Can I track users that have uninstalled my app?

Yes and no. Mobile operating system providers make it intentionally difficult to reliability detect when a user has uninstalled an app.

OneSignal does not differentiate an Uninstall vs Unsubscribe And Never Opening the App Again.

OneSignal detects the last time a device opened the app with the "Last Session" parameter. You can Export User Data to check the Subscription Status and Last Active time.

Updated 2 months ago



Users & Subscribers Guide


Managing and understanding your users in the OneSignal Dashboard.

Suggested Edits are limited on API Reference Pages

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