UTM Tracking for OneSignal: How to Build and Validate Push Notification Campaign Links

Why push notifications show as Direct traffic without UTM parameters

HTTP referrer headers are passed by browsers when a user navigates from one page to another via a link — they tell the destination server (and analytics tools like GA4) where the user came from. Email clients typically pass referrer information when a subscriber clicks a link in an email message, and social platforms pass referrer headers when a user clicks a shared link. Push notifications do not follow this pattern.

When a subscriber taps a web push notification or a mobile push notification, the operating system or browser opens the Launch URL directly — the same way a user would type a URL into the address bar. No referrer header is passed because the notification is not a web page with a referring URL. GA4's session acquisition logic classifies sessions with no referrer as Direct traffic. The result: every OneSignal push notification click without UTM parameters inflates your Direct traffic metric, while your push channel contribution goes uncounted in channel reports.

UTM parameters in the Launch URL solve this by giving GA4 the channel attribution information that the missing referrer header cannot provide. When GA4 sees utm_source=onesignal&utm_medium=push in the URL, it correctly assigns the session to the push channel, regardless of whether a referrer header was present. This is not a workaround — it is the standard method for tracking push notification traffic in GA4 and all other analytics platforms.

The correct utm_source and utm_medium for OneSignal

Use utm_source=onesignal for all push notifications sent via OneSignal — web push, mobile push (iOS and Android), and in-app messages. The source value identifies the sending platform. For utm_medium, use push for web push and mobile push notifications. This correctly labels the delivery channel for GA4's channel dimension, though GA4 does not have a default "Push" channel grouping — you will need to add a custom channel grouping rule in GA4 (Admin > Data Display > Channel Groups) that classifies utm_medium exactly matches push as a Push channel, otherwise push sessions appear under "Other channels."

OneSignal also offers Email capabilities (Journeys can include email steps). For OneSignal Email sends, use utm_source=onesignal and utm_medium=email — this ensures OneSignal Email sessions route to GA4's Email channel correctly. Keep push and email sends distinguishable in the medium dimension so your channel performance report separates push-driven traffic from email-driven traffic even when both originate from OneSignal.

• Web push notification: utm_source=onesignal, utm_medium=push
• Mobile push notification (iOS/Android): utm_source=onesignal, utm_medium=push
• In-app message with CTA button: utm_source=onesignal, utm_medium=in-app
• OneSignal Email step in a Journey: utm_source=onesignal, utm_medium=email

Building tracked OneSignal push notification URLs with mlz build

OneSignal's notification builder has a "Launch URL" field — this is the URL that opens when a subscriber clicks or taps the notification. Build your tracked URL with mlz build before opening the OneSignal notification composer, then paste the resulting tracked_url into the Launch URL field. OneSignal passes this URL directly to the browser or operating system — it does not modify or shorten the URL, so UTM parameters are preserved as-is.

# Build a tracked URL for a OneSignal push notification
$ mlz build \
  --url "https://store.example.com/flash-sale" \
  --source "onesignal" \
  --medium "push" \
  --campaign "flash-sale-jun-2026" \
  --validate

{
  "tracked_url": "https://store.example.com/flash-sale?utm_source=onesignal&utm_medium=push&utm_campaign=flash-sale-jun-2026",
  "params": {
    "utm_source": "onesignal",
    "utm_medium": "push",
    "utm_campaign": "flash-sale-jun-2026"
  },
  "destination_url": "https://store.example.com/flash-sale",
  "created_at": "2026-06-06T09:00:00.000Z",
  "link_id": "lnk_os12345a",
  "stored": true
}

# Paste the tracked_url into OneSignal's "Launch URL" field in the notification composer

The --validate flag runs mlz check against the destination URL before returning the tracked URL, confirming that the destination resolves correctly, responds with a 200 status, uses HTTPS, and has no redirect chain that might strip the query string. For flash sales and time-sensitive campaigns, validating before the notification goes out is especially important — a broken destination URL in a push notification results in subscriber trust loss and unrecoverable campaign performance.

For OneSignal Automated Messages (triggered notifications based on subscriber behavior — abandoned browse, re-engagement, anniversary), use dedicated utm_campaign slugs per automated message: utm_campaign=abandoned-browse-push, utm_campaign=reengagement-push-7-days, utm_campaign=anniversary-push. Configure these tracked URLs once in the OneSignal Automated Messages builder, not per send. Use utm_content to differentiate action buttons when a notification has multiple CTA buttons with different destination URLs.

A/B testing push notifications with utm_content

OneSignal supports A/B testing (called Message Variants in the OneSignal interface) where you send different notification titles, body text, or images to subscriber segments to determine which variant drives better engagement. If both variants link to the same destination URL, UTM parameters alone cannot tell you which variant drove a given GA4 session — unless you use utm_content to tag each variant distinctly.

# Variant A: urgency-focused headline
$ mlz build \
  --url "https://store.example.com/flash-sale" \
  --source "onesignal" \
  --medium "push" \
  --campaign "flash-sale-jun-2026" \
  --content "urgency-headline" \
  --validate

{
  "tracked_url": "https://store.example.com/flash-sale?utm_source=onesignal&utm_medium=push&utm_campaign=flash-sale-jun-2026&utm_content=urgency-headline"
}

# Variant B: benefit-focused headline
$ mlz build \
  --url "https://store.example.com/flash-sale" \
  --source "onesignal" \
  --medium "push" \
  --campaign "flash-sale-jun-2026" \
  --content "benefit-headline" \
  --validate

{
  "tracked_url": "https://store.example.com/flash-sale?utm_source=onesignal&utm_medium=push&utm_campaign=flash-sale-jun-2026&utm_content=benefit-headline"
}

# Assign variant-specific tracked URLs to each OneSignal message variant

In GA4's campaign detail report, you can filter by utm_campaign=flash-sale-jun-2026 and then pivot on the utm_content dimension to see exactly how many sessions, goal completions, and revenue each variant drove. This gives you conversion data from GA4 to complement OneSignal's own click-through rate metrics — a more complete picture of which variant actually drove results beyond the click.

OneSignal UTM tracking gotchas

OneSignal does not auto-append UTM parameters — every notification Launch URL must be manually tagged

Unlike some email platforms that offer auto-UTM settings, OneSignal does not automatically append UTM parameters to Launch URLs. Every notification you send through OneSignal — one-off campaigns, automated messages, and in-app messages with CTA buttons — requires a manually tagged Launch URL. There is no platform-level setting to enable auto-UTM for all sends. Building tracked URLs with mlz build before entering them in OneSignal is the reliable workflow. For automated message flows configured once and triggered by subscriber events, build the tracked URL at configuration time. For recurring push campaigns, build a new tracked URL with each new utm_campaign slug before creating the OneSignal notification.

Push notification traffic appears as Direct in GA4 without UTM parameters

This is not an edge case — it is the default behavior for all push notification platforms, not just OneSignal. Push notifications do not pass HTTP referrer headers. Any push notification sent with a bare destination URL (no UTM parameters) will appear as Direct traffic in GA4. Over time, untagged push traffic inflates your Direct baseline and makes it impossible to separate intent-driven direct visits from push notification clicks in attribution modeling. If you have historical push notifications without UTM parameters, you cannot retroactively fix those sessions in GA4 — the data is already attributed to Direct. Starting now: tag every new push notification.

OneSignal action buttons can link to different URLs — each needs its own tracked URL

OneSignal supports action buttons in notifications (up to two buttons on some platforms) that can link to different destination URLs. For example, a notification might have a "Shop Now" button and a "View Details" button pointing to different pages. Each action button has its own URL field — each URL must be independently tagged with UTM parameters. Build a separate tracked URL for each action button destination, using utm_content to differentiate them: utm_content=shop-now-button and utm_content=view-details-button. Without distinct utm_content values, GA4 cannot tell which button a subscriber clicked.

Mobile app deep links require UTM parameter handling by the app

For mobile push notifications that use deep links (custom URL schemes like myapp://product/123 or Universal Links), UTM parameters work differently than for web URLs. The mobile app must be instrumented to read UTM parameters from the deep link URL and pass them to Firebase Analytics or GA4 via the screen_view or campaign_details events. OneSignal passes the full Launch URL to the app — including query parameters — but whether those parameters reach GA4 depends on how the app handles them. For web push notifications targeting a browser, standard UTM parameters in the HTTPS Launch URL work reliably without any app instrumentation.

OneSignal Email journeys need utm_medium=email, not utm_medium=push

OneSignal Journeys can include both push notification steps and email steps in the same automated workflow. When tagging tracked URLs for email steps in a OneSignal Journey, use utm_medium=email — not utm_medium=push. Using utm_medium=push for email sends routes those sessions to the push channel in GA4, misrepresenting the delivery channel. Keep the medium value tied to the actual delivery mechanism: push for push notification steps, email for email steps, even within the same OneSignal Journey.

OneSignal UTM naming conventions

Recommended UTM parameter values for OneSignal, aligned with GA4 channel reporting and a lowercase-hyphenated taxonomy:

• utm_source: onesignal for all sends from the OneSignal platform — web push, mobile push, in-app messages, and OneSignal Email. Always lowercase.
• utm_medium: push for web push and mobile push notifications; in-app for in-app message CTAs; email for OneSignal Email steps in Journeys. Add a GA4 custom channel grouping rule to classify utm_medium=push sessions under a dedicated Push channel, as GA4 does not include Push in its default channel grouping definitions.
• utm_campaign: Lowercase, hyphenated slug per notification campaign or automated message. One-off campaigns: flash-sale-jun-2026, new-product-launch-jun. Automated messages: abandoned-browse-push, reengagement-push-7-day, back-in-stock-push, price-drop-push. Recurring campaigns (weekly digest, daily flash): weekly-digest-push-jun-2 — include a date suffix to distinguish instances in GA4 campaign reports.
• utm_content: Per-notification CTA or A/B variant identifier. Use when a notification has multiple action buttons or when running message variants. Examples: shop-now-button, view-details-button, variant-a, variant-b, urgency-headline. Omit when a notification has a single CTA and no variants being tested.
• utm_term: Rarely used for push notifications. Consider using to segment audiences: utm_term=active-subscribers vs. utm_term=at-risk-subscribers when sending the same campaign to different segments with different CTA messaging.

See the UTM naming conventions guide for the full cross-platform reference and the UTM tracking for developers guide for programmatic generation and validation at scale.

FAQ

Does OneSignal provide UTM auto-tracking for push notifications?

No. As of 2026, OneSignal does not offer a platform-level setting to automatically append UTM parameters to all push notification Launch URLs. Each notification's Launch URL must be manually tagged. OneSignal does provide its own internal click analytics dashboard that tracks notification delivery rates, click-through rates, and conversion events (if you install the OneSignal SDK and define conversions within OneSignal). But OneSignal's internal analytics and GA4's session attribution are separate systems — GA4 requires UTM parameters in the Launch URL to correctly attribute push sessions, regardless of what OneSignal's internal dashboard reports.

What utm_medium should I use for OneSignal push notifications?

Use utm_medium=push for both web push and mobile push notifications. This is the most commonly used convention for push notification UTM tracking. GA4 does not have "push" as a defined channel in its default channel grouping — sessions with utm_medium=push will appear under "Other channels" unless you add a custom channel grouping rule in GA4 (Admin > Data Display > Channel Groups) that classifies utm_medium exactly matches push as a dedicated Push channel. Some teams use utm_medium=web-push and utm_medium=mobile-push to distinguish the two delivery types in GA4 — this requires two custom channel grouping rules but gives finer granularity in channel reports.

How do I validate that my OneSignal push notification Launch URL is correct before sending?

Run mlz build --url "your-destination-url" --source "onesignal" --medium "push" --campaign "your-campaign-slug" --validate before creating the OneSignal notification. The --validate flag runs a full URL check — confirming HTTPS, resolution (200 response), redirect chain integrity, and query string preservation through any redirects. Copy the returned tracked_url directly into OneSignal's Launch URL field. If you want a more thorough check of the landing page's OG tags and social preview metadata (relevant if the notification links to a landing page that may also be shared on social), run mlz inspect "your-tracked-url" to get a full OG, Twitter Card, and viewport readiness report for the destination.

OneSignal Journeys has both push and email steps — how do I tag the email steps?

For email steps in a OneSignal Journey, use utm_medium=email — not utm_medium=push. Build a separate tracked URL for each Journey step, with the medium value matching the delivery channel for that step. For example, in an abandoned cart Journey: push step 1 gets utm_source=onesignal, utm_medium=push, utm_campaign=abandoned-cart-push-step-1; email step 2 gets utm_source=onesignal, utm_medium=email, utm_campaign=abandoned-cart-email-step-2. This ensures GA4 can report the email and push contributions of the same Journey separately in channel and campaign dimension reports.

Can I use the OneSignal REST API to programmatically build notifications with UTM-tagged Launch URLs?

Yes. If you use the OneSignal REST API or SDKs to create notifications programmatically (common for transactional push scenarios — order updates, shipping alerts, personalized recommendations), build the tracked URL first with mlz build --format json, extract the tracked_url from the JSON response, and pass it as the url parameter in your OneSignal API call. This ensures every programmatically created notification has a correctly tagged Launch URL without manual intervention. For high-volume transactional push (thousands of notifications per day), consider using the MissingLinkz REST API directly — POST /v1/build — to generate tracked URLs within your existing backend pipeline before handing them to the OneSignal API. See the programmatic UTM link guide for the API integration pattern.

Related reading