Topic-based subscription widget
For Web only.
Topic-based widget gives you a simple way to manage the types of push notifications your users subscribe to and target your campaigns to relevant user segments.
Use the topic-based widget to:
    increase user activations: users who have options when subscribing are more likely to opt-in. Users are free to decide which message categories they'd like to receive from you, meaning that these messages are relevant to, expected by, and valuable for the users.
    grow CTR: users are interested in receiving and opening messages they've subscribed to, skyrocketing your campaigns' CTR.
    manage user subscriptions: users can change their subscription preferences at any time, and you can update the subscription topics if needed.

How it works

Topic-based widget creates segments of users who opted-in to receive from you messages of a particular topic. That's how it works:
    1.
    You set a list of topics and publish the subscription prompt with that list. Basically, it's a customizable Rich Media webpage containing topic names and checkboxes for subscribing to each topic.
    2.
    Users, when seeing the subscription prompt, can select the topics they are most interested in.
    3.
    When sending a push campaign, you can select the topic your message belongs to — the message will be sent to only those users who have subscribed to that topic.
Topics selected by a user are saved as that user's Subscription Segment tag values.

How to implement

Important!
For a website, integrate the latest Pushwoosh Web SDK using this guide. For mobile, integrate Pushwoosh SDK:
    for iOS v5.19.2 and above,
    for Android v5.19.2 and above.

Web integration

To show the widget on site load

    1.
    Integrate the latest Pushwoosh Web SDK using this guide.
    2.
    Use the autoSubscribe:true parameter while initializing the WebSDK.
    3.
    Website visitors who are not subscribed to pushes will see the widget once the site is loaded.
Frequency capping
If a user clicks "Deny" or ignores the topic-based widget, our SDK will show the widget again in 4 hours after.
The widget is capped to 3 total impressions. If a user denies three times in a row, they will not see the widget anymore and should change their opt-in preferences manually from browser settings.

To show the widget at another moment

The subscription prompt is the event-triggered Rich Media page displayed to your web users as a pop-up window, and for mobile users — as an In-App Message. To display this subscription prompt to users, call the postEvent API method to send the Subscription Segments event to Pushwoosh.
1
Pushwoosh.push((api) => {
2
// if permission default
3
// show subscription segments widget
4
if (Pushwoosh.driver.checkIsPermissionDefault()) {
5
Pushwoosh.subscriptionSegmentWidget.showPopup();
6
return;
7
}
8
// else - show Subscription Segments in-app
9
api.postEvent(SUBSCRIPTION_SEGMENT_EVENT, {});
10
});
11
12
// Make sure to enable In-Apps in your Pushwoosh WebSDK init params
13
14
Pushwoosh.push([
15
'init',
16
{
17
applicationCode: 'XXXXX-XXXXX',
18
19
inApps: {
20
enable: true
21
}
22
}
23
])
Copied!
When deciding on when to display the prompt, take into account the user flow on your website or in your app. For example, you can add the My Subscriptions button to the app user profile so that the user clicking that button will see the list of topics to subscribe.

Mobile integration

Out-of-the-box implementation

    1.
    Integrate the SDK following the iOS, Android, or cross-platform guides.
Make sure to integrate the latest SDK versions:
    for iOS v5.19.2 and above,
    for Android v5.19.2 and above.
2. Create and publish the widget.
To show the widget, you basically don't need any additional coding: make sure the SDK is integrated properly, then create a Topic-based subscription widget as described below and publish it.
The SDK will call the PushNotifications method which triggers the widget. Once a user chooses a topic and confirms their choice, they'll see the native iOS or Android subscription permission request. When they enable push notifications for your app, the corresponding tag values are assigned to that user's device, so you'll see the Subscription Segments tag's stats changes correspondingly.

Event-triggered widget

Make sure to integrate the SDK into your project.
The subscription prompt could be triggered by the Events you set up. To set up the event-triggered widget's showing logic, call the postEvent API method to send the Subscription Segments event to Pushwoosh.
Swift
Objective-C
Android
1
PWInAppManager.shared().postEvent("Subscription Segments", withAttributes: nil)
Copied!
1
[[PushNotificationManager pushManager] postEvent:@“Subscription Segments” withAttributes:@{}];
Copied!
1
PushwooshInApp.getInstance().postEvent("Subscription Segments");
Copied!
Subscription Segments event is created by default for all accounts with Subscription Segments enabled.
While deciding on when to display the prompt, take into account the user flow on your website or in your app. For example, you can add the My Subscriptions button to the app user profile so that the user clicking that button will see the list of topics to subscribe.

Creating a topic-based widget

To enable topic-based widget for a particular app, go to the Subscription Prompt section of the app menu and check the corresponding checkbox.
If you have been using the default widget and change it to the topic-based one, the new widget will be published in 5-10 minutes.
Then, set a list of topics you are going to offer your users.
The topics' names are displayed to users when they decide on their subscription, so make sure these names are descriptive and give a clear understanding of what kind of content each category contains.
For existing users, define whether they will be subscribed to a topic automatically or not.
    When the Existing users checkbox is set to Subscribed, Pushwoosh will start assigning the corresponding value for the Subscription Segments tag for all of your users existing to the moment. That process is conducted in the background and is indicated with the Pending status next to a topic name. It may take up to several hours, depending on how large your current user base is. When done, the status is switched to Processed, and the number of the topic subscribers is shown, including all devices with or without push tokens.
    Once you send a push to any of the topic-based segments, we update the number of topic subscribers to display only those devices that have push tokens assigned. Every time you send a message, the number of subscribers of each topic will be updated.
Users who are subscribed already will see the subscription prompt with topics in their actual statuses. That means, even if a user opted-in to receive your notifications and, therefore, is subscribed by Pushwoosh to topics enabled by default, this process may be not completed at the moment, so the pending topics will appear disabled for that user.
For new users, the subscription prompt will appear with all topics checked by default.
Subscription prompt for new users
The number of subscribers of a particular topic is displayed in the Audience column near the topic name. These numbers are updated with newly subscribed users in real time.
Once you send a push to any of the topic-based segments, we update the number of topic subscribers to display only those devices that have push tokens assigned. Every time you send a message, the number of subscribers of each topic will be updated.
Each topic has its own code needed to send messages to that topic's subscribers via API.
Next, customize the appearance of your widget.
Please note that the subscription prompt won't be shown to users until you press Save on the bottom of the page.

Customizing topic-based widget

Provide understandable and explicit texts in Header, Sub-header, and Unsubscribe text fields to tell your users what they can subscribe to.
Editing texts
Adjust colors of texts, controls, and background to fit your website or app style.
Customizing appearance
Click Save to save changes. Then, click Publish on the top of the page to start showing the widget to users.
Please note that the subscription prompt won't be shown to users until you press Save on the bottom of the page.
If you'd like to remove the widget from your site, select the My custom widget option and press Publish.
Important!
    If you delete a topic, its tag value is removed from the Subscription Segment tag.
    If you delete a topic, you cannot create a new one with the same name unless you publish the updated prompt.
    If you already have active subscribers in your app, they will be subscribed to the topics for which you set the checkbox state to "Selected". They can change their subscription preferences at any time after that.
    If you change the topic's checkbox state from "Selected" to "Unselected," users subscribed previously to that topic will remain subscribed. To change their subscription, delete the topic, save changes, and publish the prompt. You can continue subscribing new users to that topic — to do so, add a new topic with the same name and choose the "Unselected" checkbox state (existing users won't be subscribed).
    If you add a topic to the existing list and set its checkbox state to "Selected", Pushwoosh will start subscribing your existing users to that topic in the background. They can opt-out when see the updated prompt.
    In terms of subscriptions to topics, there are three possible states for a user — they can be subscribed to a topic, not subscribed to a topic, or unsubscribed from it.
    You can edit topic names, and subscribed users will remain subscribed.
If a user unchecks all topics or some of them in the subscription prompt and submits changes, they are still subscribed to your app's notifications in general. That means they cannot be targeted as Subscription Segments; however, you can reach out to them with broadcast messages or pushes targeted based on Tags and Filters.

Sending messages

Control Panel

To target a push notification to users subscribed to a particular Subscription Segment, go to the One-time push section of Control Panel and open the Segmentation tab.
Toggle Subscription Segments ON, then select the topic the message belongs to.
If you select both Subscription Segment and Filter, the message will be sent to users who belong to that Subscription Segment and that Filter simultaneously.

API

To send a topic-based push notification to a particular segment, add the "subscription_segments" parameter to your /createMessage request. The "subscription_segments" param is an array of segment codes. You can find a segment code below the topic name in the Subscription Segments section of Control Panel.
Example
1
{
2
"request": {
3
"application": "XXXXX-XXXXX",
4
"auth": "kVbUA.....OUtzcMa0XN",
5
"notifications": [{
6
"send_date": "now",
7
"content": "Hello world!",
8
"subscription_segments": ["4E0D0-C2AAF"]
9
}]
10
}
11
}
Copied!
Last modified 1mo ago