Segmenting Users with Tags

When a browser subscribes to your web push notifications, you can attach tags (labels) to that subscription.
Tags allow you to group devices by user preferences, properties, or behavior, and then send targeted notifications to those groups.

How Tags Work

  • Tags can be added when the subscription is first created or updated at any time later.
  • Unlike user IDs, tags can be set without a signature.
  • This means users can potentially modify their own tags, so for sensitive tags you should use random, hard-to-guess values.

It’s often easier to gather all relevant tags for a user and then update the subscription at once rather than adding or removing them one by one.

Managing Tags

You can:

  • Add new tags to a subscription.
  • Replace all existing tags with a new set.
  • Remove tags when they are no longer relevant.
  • Update tags from your backend using the Subscriptions API for server-side management.

Tags complement user IDs. For example, you might:

  • Use tags for broad audience segmentation (e.g., "Sports", "Offers").
  • Use user IDs for precise targeting (e.g., sending transactional messages to specific accounts).

Tag Format

Tags can contain:

  • Letters, numbers, and underscores.
  • Unicode letters, marks, and numbers.
  • The characters: -, ., :, @, #.

Any invalid characters should be removed before saving tags.
While there is no limit on a single tag, the total size of all tags for one subscription cannot exceed 2000 bytes.

Targeting with Tag Expressions

When sending notifications, you can use boolean expressions to match subscriptions:

  • tag1 → Matches devices with tag1.
  • !tag1 → Matches devices without tag1.
  • tag1 && tag2 → Matches devices with both tags.
  • tag1 || tag2 → Matches devices with either tag.

Complex expressions with parentheses are also supported.
Operator precedence is:

  1. ! (NOT)
  2. && (AND)
  3. || (OR)

Tags vs User IDs

Tags are linked to browser subscriptions, not users.
If a user accesses your site from multiple browsers, each browser has its own set of tags.

Use tags when:

  • You want per-device preferences (e.g., "Send offers only to my phone").
  • You don’t need synchronization between devices.

Use user IDs when:

  • You want consistent tracking across all devices for a user.
  • You need to target specific accounts reliably.

Synchronizing Tags Across Devices

If you want consistent tags for a user across devices:

  1. Initialize each new subscription with the user’s current tags.
  2. Update tags from your backend whenever the user’s preferences change.
  3. Use the Subscriptions API to find all devices for a user and apply updates.

If strict consistency is not required, allow eventual consistency by updating tags when the user visits your site.

Best Practices

  • Use tags for audience segmentation and campaign targeting.
  • Use user IDs for secure, precise, transactional messages.
  • For sensitive targeting, use random, unguessable tag values.
  • Keep the total tag size under 2000 bytes to avoid delivery issues.

Tags give you the flexibility to run targeted, relevant, and engaging push notification campaigns without complex database synchronization.