The Telerik Platform product is retired.Learn more

Targeting Push Notifications

Targeting Push Notifications

With Telerik Platform you can send push notifications to either all devices in your application or to a subset of them. The process of creating and selecting an audience is called targeting.

When targeting, you are building a filter expression as part of the JSON notification object that you need to pass to the send operation.

Content at a glance:

Building a Filter

A filter is a standard JSON object that is assigned to the Filter field of the JSON notification object.

    "Parameters.City": "Tokyo"

Once you have build the filter object, you need assign it to the notification object's Filter field in a stringified form:

  "Filter": "{\"Parameters.City\": \"Tokyo\"}",
  "Message": "Personal message"

Filtering Criteria

You can include these types of criteria in your filters:

User Account Fields as Filtering Criteria

If you are managing your user accounts through the Telerik Platform User Management feature you can filter based on the user account object fields.

A precondition is that the device registration's UserId field must match the user account's Id field. To achieve that, ensure that the user is logged in when you register the device for push notifications with Telerik Platform.

User-account related parameters are referred to using the following notation:


Where FieldName is either of the following:

  • A built-in User object field name such as Username, Email, or IsVerified
  • A custom User object field name that you have added such as SchoolName or MemberSince


For example, you can create a custom filter on a field in the user's account object that is named Referrer like this:

 "User.Referrer": "jsmith"

Device Registration Fields as Filtering Criteria

The device registration object contains various parameters that you can use for filtering. These include things like platform type, hardware model, and locale. For the full list, see Table of Registration Object Fields. Custom parameter, although technically part of the device registration object, are discussed in Custom Parameters as Filtering Criteria.

Example: Use the following expression to filter only Windows Phone devices:

"Filter": "{\"PlatformType\": 1}"

Custom Parameters as Filtering Criteria

You can choose to filter your devices based on values stored in the device registration's customParameters object.

Custom parameters are key-value pairs where the key is the parameter name. Parameters are typically set on device registration but you can add or update them subsequently from your app.

Use the following notation to refer to a custom parameter in your filter:



The following code snippet refers to a pair of custom parameters for AgeGroup and City:

    "Parameters.AgeGroup": 1,
    "Parameters.City": "London"

How Are Filters Applied

After you have a filter criteria definition in a JSON object, you assign it to the Filter field of your push notification object in a stringified JSON form.

A filter is always applied on the fly just before sending the push notification. You cannot store the filtration result and reuse it. This ensures that you always get an up-to-date segment that includes the latest snapshot of your user base.

This is important when scheduling a push notification for later sending. The devices will be filtered at the moment of sending the notification and not at the moment of scheduling the push notification.

Building Advanced Filters

Using native MongoDB syntax you can build filter expressions using comparison operators, logical operators, and regular and matching expressions.

Go to these articles to learn more about native MongoDB operators:

Example: Use the following expression to target a small number or devices by their device ID:

"Filter": "{\"$or\":[{\"Id\":\"device id 1\"},{\"Id\":\"device id 2\"}]}"


Examine the examples in this section to gain a better understanding of how filtering work to target various subsets of your registered devices.

Targeting a Single Device

You can send a push notification to a single device by filtering for a device-specific parameter. This can be any parameter such as platform type, device ID, user account ID, or any other parameter from the Parameters or User collection or the device registration object that is unique to the device.

If you are leveraging the Telerik Platform User Management feature, it is the most convenient to target a device based on existing fields in the Users content type such as Email. For example:

  "Filter": "{\"User.Email\": \"\"}",
  "Message": "Personal message"

If you don't integrate Telerik Platform User Management in your app, you can create a unique custom parameter during the device registration. Assume you are creating a unique user account name for each device your app is installed on. You can add it to the device registration like this:

"customParameters": {
    "UserAccount" : "jsmith"

Then, in the Filter line of your push notification simply include the parameter:

  "Filter": "{\"Parameters.UserAccount\": \"jsmith\"}",
  "Message": "Personal message"

Targeting Channel Subscribers

A popular push notifications scenario is sending push notifications to users based on channel subscriptions.

Assume you are building a sports app that offers news and event information for various sports, each of which has its own channel. Users can subscribe to any combination of channels to keep up to date with the sports.

Here is how you can send a push notification to all users subscribed to the motorSports channel:

First, register the device with the proper parameters. You can place all the channels a user is subscribed to in a JSON array as follows:

"customParameters" : {
      "channels": ["motorSports", "football", "winterSports"]

Or in the case of a single channel:

"customParameters" : {
      "channels": "motorSports"

Then create the appropriate filter. To target all users who have subscribed to a particular channel (motorSports):

   "Filter":"{\"Parameters.channels\":\"motorSports\"}",  // must be a JSON string
         "title":"Upcomming Motoring Events",
         "message":"Tap to see all upcoming events in your area",
         "alert":"Tap to see all upcoming events in your area",
      "customData":"Custom data for iOS"

This payload creates a segment that will target all users subscribed to motorSports even if they have other channels in their subscriptions.

If you want to target multiple channels in a single push notification (such as motorSports and winterSports) change the Filter line in the above example to the following:


This filtering criterion uses the logical operator or which means that a notification will be send to users that are subscribed to at least one of the listed channels. You can also list three or more items after an OR operator.

There is another approach to targeting subscribers to a single or multiple channels. Using the array operator $in you can match all devices that have any of the listed values in a custom parameter that is either:

  • An array of values
  • A single value
"Filter": "{\"Parameters.channels\": {\"$in\": [\"motorSports\", \"winterSports\"]}}"

If you use the logical operator $and instead, you can target users that are subscribed to each of the listed channels, like this:


An alternative notation uses the $all operator. Leveraging it in the following manner yields the same result:


See Also

Contact us: +1-888-365-2779
Copyright © 2016-2018, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.