Skip to main content
Tag web push subscribers with contextual data โ€” such as the page topic or URL path they subscribed from โ€” to deliver targeted follow-up campaigns. This tutorial covers detecting the opt-in, applying tags, building segments, and automating messages. Prerequisites:

โ€‹
Setup

โ€‹
1. Tag users with page-specific metadata

When a user subscribes to push notifications, use the PushSubscription.addEventListener listener to detect the opt-in and apply tags with contextual data about the page they were viewing. 
function pushSubscriptionChangeListener(event) {
  if (event.current.optedIn && !event.previous.optedIn) {
    // User just opted in โ€” tag with subscription context
    var pathSegment = window.location.pathname.split('/')[1] || 'home';
    var pageTopic = document.querySelector('meta[name="article-topic"]')?.content || 'general';

    OneSignal.User.addTags({
      subscription_page: pathSegment,
      subscription_page_topic: pageTopic,
    });
  }
}

OneSignalDeferred.push(function(OneSignal) {
  OneSignal.User.PushSubscription.addEventListener("change", pushSubscriptionChangeListener);
});
How this works:
  • The change event fires when the userโ€™s push subscription state changes (opt-in, opt-out, token refresh).
  • event.current.optedIn is true when the user has an active subscription. Checking !event.previous.optedIn ensures tags are only applied on the initial opt-in, not on every state change.
  • window.location.pathname.split('/')[1] captures the first path segment as the subscription context. For example, if the URL is https://example.com/gaming/article-123, the subscription_page tag is set to gaming.
  • pageTopic is extracted from a <meta> tag, falling back to 'general'. Adjust this to match your siteโ€™s metadata structure.

โ€‹
2. Segment users by tag

Once tags are applied, use Segments or API Filters to target users based on those tags. For example:
  • Send a campaign to users where subscription_page is gaming
  • Create dynamic segments based on tag values and timing (e.g., hours since first session)

โ€‹
3. Automate follow-up messaging

Build drip-style campaigns that trigger messages based on when the user subscribed and what content they subscribed under. Example: Drip campaign for gaming subscribers
Segment nameFiltersDescription
Gaming 1subscription_page = gaming AND First Session > 2h AND < 24hReach out 2โ€“24 hours after subscription
Gaming 2subscription_page = gaming AND First Session > 24h AND < 48hFollow up 1 day later
Gaming 3subscription_page = gaming AND First Session > 72h AND < 96hFinal check-in after 3 days
Use upper time limits (<) to prevent users from lingering in segments once the messaging window has passed.

โ€‹
4. Combine segments with message templates

Once segments are created:
  • Build Templates for each stage in the campaign (e.g., intro, reminder, promo).
  • Use Journeys to send these messages when users enter the appropriate segment.
Example message ideas:
  • Invite to a gaming community or social group
  • Recommend trending articles related to their topic
  • Send an exclusive offer or discount code

โ€‹
Best practices

  • Use meaningful tag names and values that reflect actual user intent.
  • Extract tag values dynamically from page metadata when possible.
  • Only tag on the initial opt-in โ€” the listener example above checks !event.previous.optedIn to avoid re-tagging on every state change.
Do not include personally identifiable information (PII) such as names or email addresses in tag values. Avoid hardcoding tag values across your entire site โ€” extract them dynamically from page context.

โ€‹
FAQ

โ€‹
Do tags persist if the user clears browser data?

No. Clearing browser data creates a new Subscription. If the user re-subscribes (manually or via auto-resubscribe), the change listener fires again and re-applies the tags based on the current page.

โ€‹
Can I update tags after the initial subscription?

Yes. You can call OneSignal.User.addTags() at any time to add or update tags. The subscription listener is useful for the initial context, but you can also tag users based on ongoing behavior.

Tags

Set custom key-value pairs on users based on events or properties.

Web SDK reference

Full reference for the OneSignal Web SDK including subscription listeners and tagging methods.

Segments

Group users by properties, tags, and behavior for targeted messaging.

Journeys

Build multi-step messaging workflows triggered by segment entry or custom events.