​

What is a preference center?

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

​

Additional recommended reading

• 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

{
  "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": "sub_id_1",
      "type": "Email",
      "token": "email@example.com",
      "enabled": true
    },
    {
      "id": "sub_id_2",
      "type": "SMS",
      "token": "1234567890",
      "enabled": true
    },
    {
      "id": "sub_id_3",
      "type": "ChromePush",
      "token": "some_token_here",
      "enabled": true
    }
  ]
}

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

​

Assign categories and frequency controls

Refer to Data Tags. Tags are key-value pairs used to segment and personalize. Use string-encoded integers or timestamps to enable range-based filtering.

Users can toggle interests (e.g., sports: 1) or set frequency tags like newsletter-frequency: weekly. Use this data in Segments or the Create notification API with filters.

To update a tag, call the Update user API.

​

Collect new communication channels

Check subscriptions for type and enabled status. Show token only for email/SMS, not for push.

​

Email & SMS updates

Use addEmail, addSms SDK methods or Create subscription and Update subscription APIs. Subscription id is required for updates.

​

Push updates

If push is not enabled, prompt user.

• For mobile apps: Prompt for Push Permissions
• For web: use Native Browser Prompt or Slide Prompt

​

Disable communication channels

Use Update subscription to set enabled to false. Toggle to true to opt-in again.

​

Handle data compliance

Prevent SDK init by default and require user consent to initialize. See Handling Personal Data.

​

Delete user data

Use Delete user API to fully remove a user from OneSignal.