Pushpad Logo Pushpad

Segmenting with tags

Tags are only supported by Pushpad Pro.

When a browser is subscribed to your push notifications, you can attach some labels to its subscription. Tags can be added on subscription or at any time later using the Javascript SDK.

// add tags 't1' and 't2' to the existing subscription or create a new subscription with that tags
pushpad('subscribe', function () {}, { tags: ['t1', 't2'] });

Unlike user IDs (uids), tags can be added with the Javascript SDK without a signature. That means that an experienced user may add or remove the tags associated to his own browser subscription. If you need to create protected tags, you can use random tokens that are hard to guess.

You can also use the Subscriptions API to update the subscriptions and their tags from you backend.

After you have added some tags to the subscriptions, you can easily target groups of users when you send the notifications.

A complement to tags are user IDs. For example if you need advanced filtering over your audience you can query your database to find the users who match the criteria and then send the notification to a set of user IDs (uids).

Tags format

Tags can be any string that use a combination of the following characters: a-z, A-Z, 0-9, _, -, ., :, @, #.

Tag expressions

When you send push notifications you can target specific sets of devices using tag expressions. For example:

You can't insert parenthesis, but you can write any expression using the disjunctive normal form. From highest precedence, the operator precedence is !, &&, ||. That means for example that the expression !tag1 || tag2 && tag3 is interpreted as ((!tag1) || (tag2 && tag3)).

Tagging the browser vs Tagging the user

Tags are associated to the browser subscription, not to a user. For example a registered user may visit your website with different browsers: when you update tags with the Javascript SDK you are only altering the tags associated to the current browser. This is often the desired behavior, for example when the user can choose which notifications wants to receive on a given device. However, if you want to track some user features consistently across all his devices, you must do some extra work to make sure that all the devices associated to that user have the same tags.

Usually, if you are trying to track user preferences like "What groups the user is subscribed to?" or similar, or if you continuosly need to syncronize the user profile between your application and Pushpad, you are probably misusing tags and you should consider user IDs first.

Let's see how to syncronize tags across all the user devices (depending on your use case you may use different strategies):

  1. Initialize the browser subscription with all the tags that at the current time describe the user. You can use the Javascript SDK for that: just include all the user tags whenever you call subscribe.
  2. When the user properties change, use your backend to update the tags associated to the user devices. From your backend use the Subscriptions API to find the subscriptions associated to a given user ID; then update each subscription by adding or removing tags.

If you don't have particular consistency requirements, then you don't need to use the REST API as described above. You can just use the methods provided by the Javascript SDK to alter the tags and ensure eventual consistency. In this case, whenever a user visits your website, you can check the user profile in your database and use the status, subscribe and unsubscribe functions to realign the tags associated to the browser to the actual user profile.