OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Links, Deep-links and URLs

Concepts - Linking to internal and external URIs

When subscribers click your notifications, you can link them to a specific url or deep link to a page in the app. OneSignal provides a few options for handling links within your mobile app or website.

Launch Url

The dashboard "Launch URL" or the API url parameter is used for linking devices to certain pages of the app or website.



iOS Mobile Apps

Android Mobile Apps

http:// or https://

Required for Web Push. Will link the user to the URL upon push click.

Will open In-app Browser or default Browser depending if kOSSettingsKeyInAppLaunchURL set to true or false.

Handle Programmatically within click handler. Example below.


Not available for Web Push.

Handle Programmatically within click handler. Example below.

Handle Programmatically within click handler. Example below.

If you have a Website and Mobile App, you can open the URL on your Web Browser and deep-link on mobile by setting the web_url and app_url parameters on the dashboard or API. Using the Dashboard, check Different URL for web/app. Then input the http:// or https:// Web URL for website subscribers and app:// protocol for deep-linking in mobile apps.

Handle Launch URL on Mobile

Within your Mobile App's OneSignal SDK Notification Opened Handler you can capture the result.notification.payload.launchURL and process the deep link.

class ExampleNotificationOpenedHandler implements OneSignal.NotificationOpenedHandler {
  // This fires when a notification is opened by tapping on it.
  public void notificationOpened(OSNotificationOpenResult result) {
    Log.i("OSNotificationPayload", "result.notification.payload.toJSONObject().toString(): " + result.notification.payload.toJSONObject().toString());
    // Capture Launch URL (App URL) here
    String appURL = result.notification.payload.launchURL;
    Log.i("appURL", appURL);
let notificationOpenedBlock: OSHandleNotificationActionBlock = { result in
  let payload: OSNotificationPayload? = result?.notification.payload
  print("appUrl: ", payload.launchURL ?? "No Launch Url")

UTM Parameters

UTM parameters are tags added to URLs to measure the effectiveness of a marketing campaign. OneSignal allows you to automatically set source, medium, and campaign parameters for all your push notification's launch and action button urls.


UTM Parameters only work for Dashboard Notifications

API requests do not include UTM parameters.

  • Enable UTM parameters

Now, UTM parameters will be added automatically to the launch and action button urls of all your push notifications.

Following are the out-of-the-box values provided in the UTM parameter settings. You can also edit these to suit your campaign requirements.

  • Source = “onesignal”
  • Medium = “push”
  • Campaign = “{{ sendDate }}-{{ title }}”
    sendDate: Sent At date from the Delivery → Sent Messages statistics
    title: First 15 chars (a-z, A-Z, 0-9, underscore, hyphen) of the message title

Note: We support message variables (sendDate and title) for the campaign parameter only.

Example URL with UTM parameters appended from the settings:
https: //test. com?utm_source=onesignal&utm_medium=push&utm_campaign=2020-06-03-sale-today

  • How are UTM parameters appended to my URLs?
    With UTM Tagging enabled in app settings, you should enter the launch URLs without the UTM parameters as these will be appended automatically.

UTM parameters entered manually in the launch or action button url

No UTM parameters entered manually in the launch or action button url

UTM Settings Disabled

Only manually entered UTM parameters are appended to the url. No default UTM parameters added.

No UTM parameters added to the urls.

UTM Settings Enabled

Only manually entered UTM parameters are appended to the url. No default UTM parameters added.

Default UTM parameter values from the settings are added automatically to the launch and action button urls.

  • Can I use non-English characters in the UTM parameters?
    We don’t validate the accuracy of a URL. If there are characters other than a-z, A-Z, 0-9, underscores, or hyphen entered in a URL or UTM parameters, then please make sure the URL works before sending the notification.

Deep Linking With Additional Data

Deep Linking with Additional Data should be used if you only have Mobile Apps setup with OneSignal (no website) and do not want to open the URL within an in-app webview.

If you have both web and mobile app subscribers, you can also deep link following the above Launch URL section.

Using Additional Data or the API data parameter, you can pass some data into the notification and handle it programmatically within the SDK Notification Opened Handler and the OSNotificationPayload object.

For example, if you set customkey : profile as the data, you can detect this key: value pair in your app from result.notification.payload.additionalData and send the user to the "Profile" page or any page you decide to use for the value.

class ExampleNotificationOpenedHandler implements OneSignal.NotificationOpenedHandler {
  public void notificationOpened(OSNotificationOpenResult result) {

    JSONObject data = result.notification.payload.additionalData;
    String customKey;

    if (data != null) {
      customKey = data.optString("customkey", null);
      if (customKey != null)
        Log.i("DeepLink to page for customkey", "customkey set with value: " + customKey);
let notificationOpenedBlock: OSHandleNotificationActionBlock = { result in
  let payload: OSNotificationPayload = result!.notification.payload

  if payload.additionalData != nil {
     let additionalData = payload.additionalData
     if additionalData?["customkey"] != nil {
        // Add code to go to customkey page
^(OSNotificationOpenedResult *result) {
   OSNotificationPayload* payload = result.notification.payload;
   //Check if customkey is available in payload and go to that page
onOpened(openResult) {
    console.log('Data: ', openResult.notification.payload.additionalData);
    // Use this to check for customkey and go to that page
private static void HandleNotificationOpened(OSNotificationOpenedResult result) {
  OSNotificationPayload payload = result.notification.payload;
  Dictionary<string, object> additionalData = payload.additionalData;

  print("GameControllerExample:HandleNotificationOpened: " + message);
  extraMessage = "Notification opened with text: " + message;

  if (additionalData != null) {
    if (additionalData.ContainsKey("discount")) {
      extraMessage = (string)additionalData["discount"];
      // Take user to your store.


Github Examples

Please see our Github Examples for more:

Operating System Level Deep Linking

If deep linking into another app, then you should send the deep link as part of the regular URL field of the posted notification. See iOS's documentation on UniversalLinks and Android Deep Linking.

Note - Support for 3rd party SDKs such as Branch is limited. Sending a deep link as Example: @{ @"branch" : @"https://[branchsubdomain]/ALMc/e03OVEJLUq" } may lead to undefined behavior.

Deep link into the app store

Android - You can enter a market:// link as the launch URL and have the store schema to launch. More details on this here:


  1. you can link directly to your app using a launch url like this:
    itms-apps:// or to write a review: itms-apps://
  2. you can use Universal Links:
  3. you can use the SKStoreProductViewController in the OneSignal click event handler:

More details on this stackoverflow here:

Dynamic URLs

Using variables to write your URL is not currently supported. Use these alternate methods instead:

  1. With tags, you can add Message Personalization to the Launch URL.

  2. Deliver notifications individually to each user through our REST API, with a different URL for each. See Transactional Messages.

  3. Provide a notificationOpenedCallback. In that callback, fetch the user's OneSignal details using getIdsAvailable or getTags and redirect them to the page of your choice.

No Linking

Currently on mobile apps, anytime the user clicks the push it will open the app.

Web Push: If you do not want to link to any page or url, you can add ?_osp=do_not_open to the end of a URL like this as the launch url, this will prevent the push from going to any url upon click and will just dismiss the push.

Updated 9 days ago

Links, Deep-links and URLs

Concepts - Linking to internal and external URIs

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.