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
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 theexternal_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 datatags
- custom data you send to OneSignallanguage
- the language code for the user
subscriptions
: the messaging channels and subscription statusid
- the Subscription IDtype
-Email
,SMS
, *Push (AndroidPush
,iOSPush
,ChromePush
,SafariPush
, etc)enabled
-true
means subscribed,false
means unsubscribedtoken
- the push token, email address, or phone number depending on the subscription type
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
Checksubscriptions
for type and enabled status. Show token
only for email/SMS, not for push.
If contact info exists in your system but not yet in OneSignal, use your own
DB as a fallback to display it.
Email & SMS updates
UseaddEmail
, 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 setenabled
to false
. Toggle to true
to opt-in again.