Subscription preferences

Allow users to subscribe to different categories

The subscription preferences feature allows you to create different subscription categories to which your users can subscribe, for example, if you have different newsletters for different topics (such as Business, Lifestyle, News), you can create these categories in Xtremepush and then use them to segment your recipients.


Enabling subscription preferences

Subscription preferences if an optional feature and not enabled by default. If you wish to use this feature please contact us. It is enabled on a project basis.

Create the categories

Once the feature has been enabled on your project, navigate to Settings > Subscriptions and click on New to create a new category. The available fields are:

  • Name: The name should avoid spaces and dots, and ideally limit to lowercase letters, digits and underscore. This will allow easier use of the subscription preference through the mobile and web SDKs and the API. Example: football_news.
  • Display Name: Use this field to provide a friendly name for the category in the Xtremepush interface.
  • Channel: The messaging channel to which the category will be applied.


Available channels

This feature applies to the channels that require a subscription: SMS, email and push (mobile and web).


The example above shows two categories for email newsletters: Lifestyle and Football News.

How to manage preferences for users

Email and SMS

Navigate to Channels > Email Settings and Channels > SMS Settings to enable the feature on each of these channels.

After you do so and once you have created the different categories, the Xtremepush email and SMS preference center will list all of these, which will allow users to opt-in or opt-out from them.

In email campaigns, users can access the email preference center if you include the following code as a hyperlink to the text:


In SMS campaigns, you will need to include the unsubscribe link in your SMS message. That link will allow users to modify their preferences for specific categories.

Push channels (Android, iOS and web)

You can implement your own preference interface in your app or website and use our SDK methods to update the user profile's subscription when they select the different categories.


Device subscription

In order for devices to receive any push campaigns the standard push subscription must be enabled (which it is by default). Review our dedicated guide for more details.

JSONObject prefs = new JSONObject();
prefs.put("news", 1);
prefs.put("marketing", 0);

mPushConnector.updatePushSubscriptionPreferences(this, prefs, this);
let preferences = [
  "news": true,
  "marketing": false
XPush.updatePushSubcriptionPreferences(with: preferences) { (json: [String: Any], error: Error?) in
  // handle response
[XPush updatePushSubscriptionPreferences: @{ 
              @"news": @YES, 
              @"marketing": @NO 
withCompletionHandler: ...];
xtremepush('user', 'update', {
    'push_subscription_preferences': {
      'news': 1,
      'marketing': 0
  function(data) {
    console.log('success: ' + JSON.stringify(data))
  function(data) {
    console.log('error: ' + JSON.stringify(data))

From on-site campaigns

It is also possible to subscribe users to specific categories from on-site campaigns, when they click on a specific button.

For example, you could create a campaign to encourage users to subscribe to your movies' newsletter.


On-site campaign to get users subscribed to a 'movies' email newsletter.

To do so, navigate to Campaigns > Create a campaign > Single-stage > In-App/On-site message > select a pop-up style campaign. Fill in the required details from the Setup, Event, Segment and Schedule tabs. From the Content tab, include two buttons. On your subscription button, set the Subscribe field to the category that you created previously from the Subscriptions page.


How to set up the campaign on the Xtremepush platform.

When users click on that button, they will automatically get subscribed to this category.

From in-app campaigns

In a similar way as described above, users can opt in for push categories from in-app campaigns. This requires using the deeplink functionality.

To create the in-app campaign, navigate to Campaigns > Single-stage > Create a campaign > In-App/On-site message > select a full-screen or modal campaign type. Include two buttons, and on the desired button, from Action select the Go to deeplink option.

You can register a handler for this on Android and iOS to allow you to take action on the client side based on deeplinks. The deeplink payloads must have enough information to allow your app to make a decision on setting preferences. The deeplink format could be subpref://update?news=1 or subpref://update?news=1&marketing=1.

See example below:


To review how to configure the handlers on Android and iOS, review the following sections of our Deeplink dedicated guides:

Additionally, here is an example based on parsing the deeplink with the format shown before; that would be a flexible way of setting the subscription preferences from in-app messages.

    public void deeplinkReceived(String link, WeakReference<Context> uiReference) {

        try {
            //Turn string param into URI and break into relevant components
            Uri uri = Uri.parse(link);
            String host = uri.getHost();
            String protocol = uri.getScheme();
            Set<String> preferences = uri.getQueryParameterNames();

            //Verify the protocol and host
            if (protocol.equalsIgnoreCase("pushsubpref") && host.equalsIgnoreCase("update")) {
                //create JSON objects.
                    //jo is the param we will be passing to the updateUser function
                    //myPushPreferences is some nested JSON in jo that represents the push params to update
                JSONObject jo = new JSONObject();
                JSONObject myPushPreferences = new JSONObject();
                //loop through URI params then add each key-value pair to our 'myPushPreferences' JSON
                for (String key : preferences) {
                    myPushPreferences.put(key, uri.getQueryParameter(key));
                jo.put("push_subscription_preferences", myPushPreferences);

                // if necessary also set the subscription to 1
                jo.put("push_subscription", 1);

                //call updateUser function.
                //Params are a Context instance, the JSON object we described above, an XPCallbackHandler instance
                mPushConnector.updateUser(this, jo, new XPCallbackHandler() {
                    public void onSuccess(JSONObject response) {
                        Log.d("TAG", "Here in on success. response : "+response.toString());

                    public void onFailure(JSONObject response) {
                        Log.d("TAG", "Here in on failure. response : "+response.toString());

        } catch (Exception e){


XPush.registerDeeplinkHandler { x in
  guard x.hasPrefix("pushsubpref"), let query = URLComponents(string: x)?.queryItems else { return }
  var params: [String: String] = [:]
  for q in query {
    params[] = q.value
  XPush.updateUser(with: params) { jsonResponse, error in
[XPush registerDeeplinkHandler:^(NSString *x) {
  if !([x hasPrefix:@"pushsubpref"]) {

  NSMutableDictionary* params = @[].mutableCopy;
  for (NSURLQueryItem* q in [NSURLComponents componentsWithString:x].queryItems) {
    params[] = q.value;
  id prefs = @{ @"push_subscription_preferences": params,
                @"push_subscription": @(1)
  [XPush updateUserWith:prefs completionHandler:^(NSDictionary * _Nullable jsonResponse,
                                                  NSError * _Nullable error) {

Review users' subscribed categories

It is possible to review users' individual preferences from Data > User profiles by navigating to the Channels tab. When there are categories created, the subscriptions to each channel will show the number of categories. The user in the example below is subscribed to one out of four categories for email and for one out of two categories for web push.


By default, when you import email addresses or mobile numbers into Xtremepush or when a device is generated by the SDK the user will be marked as subscribed. Even if a user is not subscribed to any specific category, the green tick will show against the channel. This status can be altered manually by clicking the Options menu > Unsubscribe.

For example, if a user is showing subscribed to 0/4 but has the green tick for email marketing that means they are subscribed to emails but for none of those categories:


To review and manage the individual subscriptions to each category click on each of the line items.


This user is unsubscribed from 'Movies' and subscribed to 'Nature'. They haven't stated whether they would like to be subscribed to 'Lifestyle' or 'Football News'.

Segment based on subscription preferences

It is possible to segment based on users' subscription status to the different categories. To do so, either from the segmentation on a campaign level (from the Segment tab) or directly from the segmentation engine (Data > Audiences > Segments > Create a segment), select the condition Engagement > Subscription Prefs. Select the desired category. It will be possible to segment based on who is subscribed or not subscribed to that specific category.


The example above shows a segmentation by users subscribed to the category 'Nature' for push channels.