Send Push Notification to Subsets of Your App Users

Updated on 29. July 2021 by Jan Bunk


The features described on this page require the push notifications addon. Please contact us if it's not enabled for your app yet.

The basic concept on how you can send push notifications to a group of users of your app is as follows:

  1. Your user John opens your app (for this example we will assume it's a shopping app).
  2. John performs an action that makes him part of your target group, for example pressing a button to subscribe to notifications about discounts on kitchen utensils. The action could also just be browsing the kitchen utensils section of your app which could mean that John is interested in products for his kitchen.
  3. Your website calls the javascript function "setNotificationTopicSubscriptionStatus" with the name of the topic you want to subscribe John to, for example "kitchen".
  4. Later you can send a notification to John and all the other users that are subscribed to this topic. For example, if you have a discount code on kitchen articles, you could send a notification to everyone subscribed to the "kitchen" topic to let them know about the discount.

Available Javascript Functions

You might want to check out the executeWhenAppReady() function of our app-helper script. It ensures that your website doesn't try to interact with the app before it's ready or when your website is loaded using a regular browser.

When you want to subscribe an app instance to a push notification topic, simply call the setNotificationTopicSubscriptionStatus function with the new subscription status (true = subscribed, false = unsubscribed) and your desired topic name.


<script>
    try {
        await setNotificationTopicSubscriptionStatus(true, "mytopic");
    }
    catch (e) {
        // Can occur if:
        // - you passed an invalid topic name.
        // - you didn't pass all necessary parameters to setNotificationTopicSubscriptionStatus().
        // - the app couldn't subscribe to the topic, for example because of connection issues. Should be very unlikely.
        // - the app couldn't connect to the native code. Should be very unlikely.
        // - push notifications are not enabled for your app
        console.log(e);
    }
</script>
    

Things to keep in mind:

  • The topic must match the following regex: [a-zA-Z0-9-_.~%]{1,850}
  • Although unlikely, the subscribing could fail, so make sure to catch potential errors.

You might also later want to get a list of topics the app instance is subscribed to. The return value is a list of strings.


<script>
    try {
        var topics = (await getSubscribedNotificationTopics())["topics"];
    }
    catch (e) {
        // Can occur if:
        // - the app couldn't connect to the native code. Should be very unlikely.
        // - push notifications are not enabled for your app
        console.log(e);
    }
</script>
    

Sending a Topic Notification via the webtoapp.design API

Get your app-specific API key from your app dashboard.

Send your API key as a query in the URL and the request body in the JSON format.