Segmenting with tags

When a browser is subscribed to your web push notifications, you can attach some labels to its subscription. Then you can use tags for sending web push notifications to groups of recipients with given preferences or properties. The tags associated to a subscription can be added when the subscription is created or at any time later using the Javascript SDK:

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

// replace all tags for the existing subscription
// or create a new subscription with these tags
pushpad('subscribe', function () {}, { replaceTags: ['t1', 't2'] });

// set the tags for the existing subscription
// or for any subscription created later using subscribe
pushpad('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.

Usually it is easier to gather all tags for a user in one place and then update the subscription once, by replacing all tags, instead of trying to add or remove tags one by one. See this example.

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:

word characters, including ASCII (a-z, A-Z, 0-9, _) and the Unicode general categories Letter, Mark, Number, Connector_Punctuation
the characters -, ., :, @, #

If you have arbitrary strings that you want to convert into tags, then you need to remove invalid characters. For example:

var tag = s.replace(/\W/g, ''); // you can also keep other Unicode characters if you want

Tags size

Currently there aren't any limits on a single tag. However the total size of the tags associated to a single subscription cannot exceed 2000 bytes.

Tag expressions

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

tag1 will match only subscriptions that have tag1.
!tag1 will match only subscriptions that don't have tag1.
tag1 && tag2 will match only subscriptions that have both tag1 and tag2.
tag1 || tag2 will match only subscriptions that have tag1 or tag2.
!tag1 || tag2 && tag3 will match only subscriptions that don't have tag1, or that have both tag2 and tag3.

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):

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.
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. See this example.