Subscriptions

Managing your user's Subscription ID.

πŸ“˜

You're Viewing User Model Documentation πŸŽ‰

OneSignal is in the process of migrating from a device-centric model (player ID) to a new user-centric data model (OneSignal ID). To learn more, check out the User Model Migration Guide.

Please refer to Version 9 of our documentation for device-centric information.

Subscription

A subscription refers to the ways a user can receive messages sent from OneSignal, like push notifications, SMS, and email. These messaging channels are each assigned a Subscription ID to uniquely identify that specific channel. In-app messages do not have a Subscription ID.

Subscription Properties

Subscriptions have the following properties.

PropertyDescription
Subscription IDUUID assigned by OneSignal to represent the subscription. Cannot be edited. Can be used to update subscriptions through the API.
ChannelHow the user can receive messages. Each subscription belongs to a single channel: Push Notifications, Email, and SMS each represent a channel and have an unique Subscription ID.
Subscription StatusDashboard The checkmark means they are subscribed and can receive messages for that channel.
- Not Subscribed means the device cannot get messages.
- Never Prompted means the device was not shown the native permission prompt, this is the required prompt and not an In-App Message. See How to Prompt for Push Permissions with In-App Messages.
- Permission Not Granted means the user was shown the native permission prompt but clicked the deny button.

API invalid_identifier property set to true means unsubscribed and cannot get messages.
SessionsWeb & Mobile only. The number of times this subscription has opened your app or visited your website. A new session is created when the user opens the mobile app or opens the website in a new tab/window after it is put out of focus for more than 30 seconds.
Session DurationWeb & Mobile only. The total number of seconds the user's device has had your app open. See How is usage duration calculated.

Web Push Subscription Lifecycle

The Web Push Subscription ID is created for a browser profile when the user opts-in (aka subscribes) to push notifications on your website. See our Web Prompting Guide for more details on getting permission.

The Web Push Subscription ID will never change. However, a new Subscription ID will be assigned to that same user's browser profile when:

  1. Clearing browser data or cookies, then returning to the website. In this case, the original Subscription ID will eventually be marked as unsubscribed. See below Push Notification Subscription Tracking for details.
  2. Deleting the original Subscription ID, then clearing browser data and returning to the site.

There are 2 options for users to opt-out (aka unsubscribe) from receiving push notifications:

  1. Go into the browser's notification settings and unsubscribe from the website.
  2. The OneSignal SDK and API provides prompts and methods to disable push at the OneSignal level. In this case, the push token is still subscribed and your website's notification settings are still subscribed, but the user is marked as unsubscribed in OneSignal and cannot be sent push from OneSignal until re-enabled.
    See the SDK method to opt-out of push or Update subscription API.

See below Push Notification Subscription Tracking for details on how OneSignal automatically tracks subscription change events.

Mobile App Push Subscription Lifecycle

When the OneSignal SDK is initialized in your mobile app, it creates a Subscription ID for that device. The user must opt-in (aka subscribe) to receive push notifications for your app. See How to Prompt for Push Permissions with In-App Messages.

The Mobile Push Subscription ID will never change. However, a new Subscription ID will be assigned to the that same user's device when:

  1. Uninstalling and re-installing the mobile app on the same device. In this case, the original Subscription ID will eventually be marked as unsubscribed. See below Push Notification Subscription Tracking for details.
  2. Deleting the original Subscription ID and opening the app again on the same device.

There are 3 options for users to opt-out (aka unsubscribe) from receiving push notifications:

  1. Uninstall the app.
  2. Go into the device's notification settings and unsubscribe from the app.
  3. The OneSignal SDK and API provides methods to disable push at the OneSignal level. In this case, the push token is still subscribed and your app's notification settings are still subscribed, but the user is marked as unsubscribed in OneSignal and cannot be sent push from OneSignal until re-enabled. See the SDK method to opt-out of push or Update subscription API.

See below Push Notification Subscription Tracking for details on how OneSignal automatically tracks subscription change events.

Push Notification Subscription Tracking

The subscription status will be updated in OneSignal automatically when the user:

  1. Interacts with the OneSignal SDK. You can capture this event with our Subscription Observer methods and send to your Database.

  2. After sending 2+ notifications to the unsubscribed device.

    1. Devices using FCM (Android Mobile Apps and Web) will alert OneSignal that the device is unsubscribed immediately after the 2nd notification is sent to the unsubscribed device.
    2. Devices using APNS (iOS devices like iPhone/iPad) will alert OneSignal that the device is unsubscribed after some time has passed between the first notification to the unsubscribed device and the 2nd notification sent.

Example sending 2+ notifications to detect unsubscribed devices:

  • Notification 1 sent and user receives on device, then user unsubscribes.
  • Notification 2 sent, the OneSignal Dashboard shows "Delivered" but the user does not actually receive it.
  • Notification 3 sent, the OneSignal Dashboard shows Failed (Unsubscribed). On iOS, it may take additional notifications and time for the unsubscribed event to be sent to OneSignal from Apple.
  • Notification 4 will not be sent to that device.

πŸ“˜

No Network Connection

If the device is no longer connected to the internet (eg it is turned off, destroyed, or reset) then it cannot report back to Google/Apple that it can no longer receive notifications.

In this case, you will want to delete older subscriptions.

🚧

iOS Unsubscribe Detection

To protect user privacy, Apple doesn't want developers to know when a user removes the app. Some details provided by Apple can be found here: https://developer.apple.com/forums/thread/670868

If a device unsubscribes and opens the app, OneSignal detects this unsubscribe event right away and updates the record 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 unsubscribe event.

Apple will wait a random amount of time, typically over 14 days, before reporting a device is unsubscribed. The unsubscribed detection requires at least two notifications to be sent to the app, after the app is uninstalled.

Apple also has an edge case where development apps must have at least one currently installed in order to determine that another one is uninstalled and can't get notifications (in addition to the random multi-day delay involved). Details here: https://developer.apple.com/library/archive/technotes/tn2265/_index.html#//apple_ref/doc/uid/DTS40010376-CH1-TNTAG34

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


Email Subscription Lifecycle

Each email address will have its own unique Email Subscription ID. There can only be a single instance of the email address within a OneSignal app.

The Email Subscription ID can only be associated with one user at a time. For example, if "user_A" is assigned "email_1" and then "user_B" is assigned "email_1", the Subscription ID for "email_1" is removed from "user_A" and assigned to "user_B".

An Email Subscription ID will be opted-in aka subscribed when:

An Email Subscription ID will be opted-out aka unsubscribed when:


SMS Subscription Lifecycle

Each phone number will have its own unique SMS Subscription ID. There can only be a single instance of the phone number within a OneSignal app.

The SMS Subscription ID can only be associated with one user at a time. For example, if "user_A" is assigned "phone_number_1" and then "user_B" is assigned "phone_number_1", the Subscription ID for "phone_number_1" is removed from "user_A" and assigned to "user_B".

A SMS Subscription ID will be opted-in aka subscribed when:

A SMS Subscription ID will be opted-out aka unsubscribed when:

Twilio Block List

Twilio provides certain default keywords like "STOP" and custom key words which a user can reply back to a message in order to opt-out of further communications. See Twilio Support for opt-out keywords (SMS STOP filtering) for details.

When a user opts-out of SMS messages, they get added to Twilio's Block List.

Once on Twilio's Block List, the only way to opt-in again is to text back the same number "START" or you can set your own opt-out keywords in Twilio.

It is a good practice to include this opt-out/opt-in sentences in your SMS such as: "Reply STOP to unsubscribed and START to resubscribe" or "Reply STOP to stop future messages, you can always opt-in by texting START".

Once they opt-back-in, you can detect this with Twilio's Webhook for Incoming Messages and mark the device as subscribed in OneSignal using the Update subscription API with enabled set to true.


FAQ

How is usage duration calculated?

Usage Duration is the number of seconds the user has interacted with the app on the device (subscription), as recorded whenever the app is in the foreground. However, this only gets sent to OneSignal once the user has been in that session for over a minute.

If the user has the app open for a minute, we track all 60 seconds. If they have the app open for 59 seconds or less and then quit the app, that data is not sent to the OneSignal servers.

If the user has the app open for under 60 seconds, then puts the app in the background and opens it again, it will still be count towards the current usage duration and once the 60 seconds gets triggered, it will send to OneSignal.


What’s Next