A Preference Center is a page on your app or website that allows your users to control how and what kind of messages they receive from you. For more details and reasons why to create a Preference Center, see A Guide to User Preference Centers.

This guide explains the technical setup needed to include a user preference center in your app or website using OneSignal's APIs. In this guide we discuss how to:

• assign topics, categories, and frequency controls with Data Tags.
• collect new communication channels (push notifications, email, SMS).
• disable communication channels if the user wants to opt-out.
• handle data compliance.
• delete user data.

Requirements

• OneSignal's Mobile SDKs version 5+ and/or Web SDK 16+
• Setting the External ID or Alias
• OneSignal does not provide any APIs for creating the Preference Center layout, only the APIs to GET, PATCH, and DELETE Users and Subscriptions
  • If you have a website and need a simple preference center, try our Category Prompt

📘

Recommendations

We highly recommend reviewing the following articles for more details and examples:

• A Guide to User Preference Centers
• Data Collected by the OneSignal SDK
• Handling Personal Data

Setup

When the user lands on your preference center, use the View user API to pull the OneSignal data for the user based on either the external_id or a custom alias you set. This will provide you the user properties and subscriptions. Helpful data includes but not limited to:

• properties: the user data
  • tags - custom data you send to OneSignal
  • language - the language code for the user
• subscriptions: the messaging channels and subscription status
  • id - the Subscription ID
  • type - Email, SMS, *Push (AndroidPush, iOSPush, ChromePush, SafariPush, etc)
  • enabled - true means subscribed, false means unsubscribed.
  • token - the push token, email address, or phone number depending on the subscription type

//Data is shortened for example
{
    "properties": {
        "tags": {
            "finance": "1",
            "tech": "1",
            "sports": "1",
            "breaking-news": "0",
            "entertainment": "0",
            "deals": "0",
            "newsletter-frequency": "weekly",
            "customer_status": "Enterprise",
            "event": "1693411710",
            "first_name": "Jon",
            "last_name": "F"
        },
        "language": "en",
        ..
    },
    "subscriptions": [
        {
            "id": "the_subscription_id",
            ...
            "type": "Email",
            "token": "the_email_address",
            ...
            "enabled": true,
            ...
        },
        {
            "id": "the_subscription_id",
            ...
            "type": "SMS",
            "token": "the_phone_number",
            ...
            "enabled": true,
            ...
        },
        {
            "id": "the_subscription_id",
            ...
            "type": "ChromePush",
            "token": "the_push_token",
            ...
            "enabled": true,
            ...
        },
    ]
}

Use the data provided to populate the preference center as needed.

Assign Categories and Frequency Controls

We recommend reviewing the doc on Data Tags, but overall, these are key: value pairs of String data that can be used for segmentation and personalization. Note that you can set integers (example unix timestamps) and decimals as Strings to segment with "greater than", "less than", and time operators.

Continuing with the above JSON example, my preference center would have options to check or toggle on topics or categories of interest based on the tags. In this case "1" means I am interested in this topic and "0" means I am not interested. This could be the same as "true" and"false".

If you allow users to frequency cap, you can setup a "timeframe" tag as well. In this example, we have "newsletter-frequency" set to "weekly".

In all these cases, you can create Segments or use the Create notification API and filters to send messages to users based on if the tag "key" = 1 and segment the newsletter-frequency customers based on weekly, daily, and monthly.

If a user decides to change any of these preferences, you can update the tags with the Update user API.

Collect New Communication Channels

If you are using OneSignal for push, email and SMS, you can check each subscriptions > type for the channel and enabled to see if they are subscribed or not. If you want to display the current email address or phone number, you can access this with the token. It would not be recommended to display the push token.

🚧

Missing Email Address & Phone Number

You may have collected email addresses and phone numbers without sending them to OneSignal yet. You can fallback on displaying the data from your database and send it to OneSignal if the data is not available.

Email & SMS Updates

If your preference center is within your mobile app or website, the OneSignal SDK provides the addEmail and addSms methods to send us this data. You can also use the Create subscription API to add a new email and/or SMS subscription to the user or the Update subscription API to change the email address or phone number of the user. Note that to update the subscription, you need the id of the subscription provided in the View user subscriptions.

Push Updates

If the user is not subscribed to push notifications (enabled is false or the type *Push does not exist), you can prompt the user to subscribe to push either on page view or after they click a button.

For mobile apps, see How to Prompt for Push Permissions with In-App Messages.

For websites, its recommended to use the Native Browser Prompt if they click a button or Slide Prompt if you want to display on page view.

Disable Communication Channels

If you want to provide an option for customers to turn off, disable or opt-out of specific channels, you can do so by setting enabled to false with the Update subscription API. If the user decides to opt-in again, set this value to true.

Handle Data Compliance

For data privacy, you can prevent the OneSignal SDK from initializing and then only allowing initialization with the user's consent. The preference center is a great place to add this functionality but it does require the OneSignal SDK. See Handling Personal Data for details on the methods to use.

Delete User Data

If you want to allow the user to delete themself, you can use the Delete user API to delete all data from OneSignal.