Handling Notifications Taps

When a user taps a notification you can route them to a specific page, pass custom data to trigger JavaScript logic, or combine both. This guide covers the two main patterns and the key distinction that trips most developers up.

How notification taps work

Notifications can include additional data. If you've included a targetUrl in the notification data, the app navigates to that URL. If you've included custom key-value pairs, it calls your JavaScript handler function with that data.

You configure both of these in the Additional Data section of any notification, whether you're sending from the OneSignal dashboard or the REST API.

flowchart TD
    A[User taps notification] --> B[App opens]
    B --> C{Payload contains targetUrl?}
    C -->|Yes| D[Navigate to targetUrl inside app]
    C -->|No| E{Payload contains custom data?}
    D --> F{Also has custom data?}
    F -->|Yes| G[Call JS handler with data]
    F -->|No| H[Done]
    E -->|Yes| G
    E -->|No| I[Open app home screen]
    G --> H

Open page (Deeplinking)

To deep-link a user to a specific page when they tap a notification, add targetUrl to the Additional Data section of your notification:

Key:   targetUrl
Value: https://yourapp.com/inbox/thread/482

targetUrl vs. Launch URL; this distinction matters

OneSignal has two different URL fields, and they behave very differently:

Always use targetUrl in Additional Data for deep-linking. The Launch URL field is designed for opening external web pages in a browser-like pop-up; it doesn't support in-app navigation features, JavaScript Bridge calls, or native plugin interactions.

Trigger JavaScript

Beyond URL navigation, you can include any custom key-value pairs in Additional Data and handle them in JavaScript when the notification is opened.

↔️Median JavaScript Bridge

Javascript

// Define this function on your page; it will be called automatically by the app when opened
function median_onesignal_push_opened(data) {
    console.log(JSON.stringify(data));
}
// Expected output
{
  'airport': 'sfo',
  'direction': 'outbound',
  'dateRange': 'week'
}

🚧

Reverse field warning

targetUrlis a reserved key in Additional Data; including it automatically triggers in-app URL navigation when the notification is tapped. If you want to conditionally navigate to a URL based on your own JavaScript logic instead, use a different key name (e.g.,openUrl, deepLink) and handle the navigation yourself inside median_onesignal_push_opened.