Hey! These docs are for version 7.0, which is no longer officially supported. Click here for the latest version, 9.0!

Links, Deep-links and URLs

Concepts - Linking to internal and external URIs

When Sending Push Messages you can direct subscribers where to go upon clicking the notification. For instance, you can set an HTTPS Launch URL and the OneSignal SDK will open the provide URL in a browser.

Mobile Apps can specify a custom URI scheme in the payload of the notification. Upon clicking the notification, you would setup the OneSignal SDK Notification Opened Event to detect the URI and direct the user to the relevant content. OneSignal does not provide deep-linking "out of the box".

The URI link can be specified using the Launch URL or Additional Data options described below.

Launch URL

The Launch URL or url API parameter can be an http/https URL that opens a webpage upon being clicked. Or can be a custom URI you setup your app to detect and handle programmatically.

If you have a Website and Mobile App, you can set Different URL for web/app with the web_url and app_url parameters on the dashboard or API.

ProtocolWebsitesiOS Mobile AppsAndroid Mobile Apps
http:// or https://Will link the user to the URL upon push click.Default behavior: Will open In-app Browser.

SDK version 3.2.1+
In Info.plist add OneSignal_suppress_launch_urls
- true will not show the launch url in an in-app browser.
- false will show the launch url in an in-app browser.
Example Suppress Launch URLs

SDK version 2.x.x can set kOSSettingsKeyInAppLaunchURL to false to open Safari.
Default behavior: Will prompt to open browser.

SDK version 4.2.0+ In AndroidManifest.xml add com.onesignal.suppressLaunchURLs
-true will not show the launch url in an in-app browser.
- false will show the launch url in a browser.
Example Suppress Launch URLs

SDK version 4.1.0- see
Change the Open Action of a Notification. Then handle programmatically within Opened Handler. Example below.
Examples:
x://
schema://
link://
Not available for Web Push.Handle Programmatically within click handler. Example below.Handle Programmatically within click handler. Example below.

Example Suppress Launch URLs

Requires OneSignal iOS SDK 3.2.1+ and Android SDK 4.2.0+

1108
<meta-data android:name="com.onesignal.suppressLaunchURLs" android:value="true"/>
<key>OneSignal_suppress_launch_urls</key>
<true/>

Handle Launch URL on Mobile

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

// Android SDK 4.x.x
OneSignal.setNotificationOpenedHandler(
   new OneSignal.OSNotificationOpenedHandler() {
     @Override
     public void notificationOpened(OSNotificationOpenedResult result) {
      // Capture Launch URL (App URL) here
      String launchUrl = result.getNotification().getLaunchURL();
      Log.i("OneSignalExample", "launchUrl set with value: " + launchUrl);
      if (launchUrl != null) {
        // The following can be used to open an Activity of your choice.
        // Replace - getApplicationContext() - with any Android Context.
        // Replace - YOURACTIVITY.class with your activity to deep link
        Intent intent = new Intent(getApplicationContext(), YOURACTIVITY.class);
        intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);
        intent.putExtra("openURL", launchUrl);
        Log.i("OneSignalExample", "openURL = " + launchUrl);
        startActivity(intent);
      }
    }
});

//Android SDK 3.x.x
class ExampleNotificationOpenedHandler implements OneSignal.NotificationOpenedHandler {
  @Override
  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 launchUrl = result.notification.payload.launchURL;
    Log.i("OneSignalExample", "launchUrl set with value: " + launchUrl);
    if (launchUrl != null) {
      // The following can be used to open an Activity of your choice.
      // Replace - getApplicationContext() - with any Android Context.
      // Replace - YOURACTIVITY.class with your activity to deep link
      Intent intent = new Intent(getApplicationContext(), YOURACTIVITY.class);
      intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);
      intent.putExtra("openURL", launchUrl);
      Log.i("OneSignalExample", "openURL = " + launchUrl);
      startActivity(intent);
    }
  }
}
// iOS SDK 3.x.x
let osNotificationOpenedBlock: OSNotificationOpenedBlock = { result in
  let notification: OSNotification = result.notification
  print("launchURL: ", notification.launchURL ?? "no launch url")
  if let appUrl = notification.launchURL {
    let storyboard = UIStoryboard(name: "Main", bundle: nil)
    // if your app is using the navbar controller within the tabbar controller
    if let postDetailVC = storyboard.instantiateViewController(withIdentifier: "PostDetailViewController") as? PostDetailViewController,
      let tabBarController = self.window?.rootViewController as? UITabBarController,
      let navController = tabBarController.selectedViewController as? UINavigationController {
         navController.popViewController(animated: false)
         navController.pushViewController(postDetailVC, animated: true)
    }
  }
}
OneSignal.setNotificationOpenedHandler(osNotificationOpenedBlock)


// iOS SDK 2.x.x
let osNotificationOpenedBlock: OSHandleNotificationActionBlock = { result in
  let payload: OSNotificationPayload? = result?.notification.payload
  print("appUrl: ", payload.launchURL ?? "No Launch Url")
  if let appUrl = payload?.launchURL {
    let storyboard = UIStoryboard(name: "Main", bundle: nil)
    // if your app is using the navbar controller within the tabbar controller
    if let postDetailVC = storyboard.instantiateViewController(withIdentifier: "PostDetailViewController") as? PostDetailViewController,
        let tabBarController = self.window?.rootViewController as? UITabBarController,
        let navController = tabBarController.selectedViewController as? UINavigationController {
            navController.popViewController(animated: false)
            navController.pushViewController(postDetailVC, animated: true)
    }
  }
}
//See: https://documentation.onesignal.com/docs/react-native-sdk#setnotificationopenedhandler-function

Deep link into the app store

You can enter the store link as the launch URL.

Android - https://developer.android.com/distribute/marketing-tools/linking-to-google-play.html
iOS - https://developer.apple.com/library/archive/qa/qa1633/_index.html

Dynamic URLs

Variables can be set within the Launch URL through Data Tags. See Message Personalization - Launch URL Substitution for details.

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 https://yoursite.com/page?_osp=do_not_open as the launch url, this will prevent the push from going to any url upon click and will just dismiss the push.


Deep Linking With Additional Data

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 additionalData property.

856

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.

// Android SDK 4.x.x
OneSignal.setNotificationOpenedHandler(
   new OneSignal.OSNotificationOpenedHandler() {
     @Override
     public void notificationOpened(OSNotificationOpenedResult result) {
      // Capture Launch URL (App URL) here
      JSONObject data = result.getNotification().getAdditionalData();
      Log.i("OSNotification", "data set with value: " + data);
      if (data != null) {
        // The following can be used to open an Activity of your choice.
        // Replace - getApplicationContext() - with any Android Context.
        // Replace - YOURACTIVITY.class with your activity to deep link
        Intent intent = new Intent(getApplicationContext(), YOURACTIVITY.class);
        intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);
        intent.putExtra("data", data);
        startActivity(intent);
      }
    }
});


// Android SDK 3.x.x
class ExampleNotificationOpenedHandler implements OneSignal.NotificationOpenedHandler {
  // This fires when a notification is opened by tapping on it.
  @Override
  public void notificationOpened(OSNotificationOpenResult result) {
    Log.i("OSNotificationPayload", "result.notification.payload.toJSONObject().toString(): " + result.notification.payload.toJSONObject().toString());
    JSONObject data = result.notification.payload.additionalData;
    String customKey;
    
    if (data != null) {
      customKey = data.optString("customkey", null);
      if (customKey != null) {
        // The following can be used to open an Activity of your choice.
        // Replace - getApplicationContext() - with any Android Context.
        // Replace - YOURACTIVITY.class with your activity to deep link
        Intent intent = new Intent(getApplicationContext(), YOURACTIVITY.class);
        intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);
        intent.putExtra("openURL", customkey);
        Log.i("OneSignalExample", "openURL = " + customkey);
        startActivity(intent);
      }
    }
  }
}
let notificationOpenedBlock: OSHandleNotificationActionBlock = { result in
    // This block gets called when the user reacts to a notification received
    if let additionalData = result!.notification.payload!.additionalData {
        print("additionalData: ", additionalData)
        print(additionalData["postId"] as! String)

        if let postId = additionalData["postId"] as? String {
            let storyboard = UIStoryboard(name: "Main", bundle: nil)
            if  let postDetailVC = storyboard.instantiateViewController(withIdentifier: "PostDetailViewController") as? PostDetailViewController,
                let tabBarController = self.window?.rootViewController as? UITabBarController,
                let navController = tabBarController.selectedViewController as? UINavigationController {
                    let dataModel = PostDataModel()
                    dataModel.postId = postId
                    postDetailVC.dataModel = dataModel
                    navController.popViewController(animated: false)
                    navController.pushViewController(postDetailVC, animated: true)
            }
        }
    }
}
^(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.
    }
  }
}

UTM Parameters

UTM parameters are query parameters added to the Launch URL to measure the effectiveness of a marketing campaign. OneSignal allows you to automatically set source, medium, and campaign parameters for your push notification's sent from the OneSignal Dashboard.

This does not work for URL set within Additional Data.

🚧

UTM Parameter Limitations

Default UTM Parameters are not supported in the following options:

  • Emails
  • Automated Messages
  • API requests
  • Using "Send Test Message" button

You will need to add UTMs directly within the Template or API request directly.

If you are using the OneSignal WordPress Plugin, you can add UTM parameters within the Plugin Settings towards the bottom within the UTM Tracking Settings.

Enable UTM parameters in Settings > Messaging > Turn on automated UTM tagging

2568

You can edit these values to suit your requirements. Default UTM parameters are as follows:

  • 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: Message variables sendDate and title are 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

Jump to UTM FAQ for more answers to frequently asked questions.

FAQ

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.

If you add custom UTMs with this feature enabled, then the custom UTMs will override the default.

Can I use non-English characters in the UTM parameters?

Yes! 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.

How to use UTM parameters?

Google Analytics, for example, uses links with UTM parameters to provide insights into your campaigns and users. These are a few common ways to use Google Analytics to understand your traffic, user behavior, and conversion data:

  • Understand Your Campaigns: Replicate the successful campaigns and improve the underperforming ones.
    On Google Analytics, navigate to Acquisition > Campaigns > All Campaigns

    • Compare metrics across different campaigns, such as users, sessions, bounce rates, and goal conversions. If you’ve used the same UTM campaign tag for different sources or mediums, you can click into that campaign and compare the performance across these different channels (source/medium).
  • Understand Your Audiences: Identify the successful user segments and improve your target audience for future campaigns.
    On Google Analytics, navigate to Audience > Demographics | Interests | Geo | Mobile

    • Add Campaign as a secondary dimension to Audience reports. Compare campaign performance across demographic segments (Age, Gender, Location, Devices) or interests (Affinity Categories, In-Market Segments).
  • Understand Your Channels: Optimize your marketing channels.
    On Google Analytics, navigate to Acquisition > All Traffic > Source/Medium

    • Compare the performance of push as a channel with your other channels, such as email or paid ad campaigns.

For more advanced analysis, filter your data by date ranges and audience segments. Add a secondary dimension for deeper insight. Set up goals, events, and custom data to track conversions.