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

Other Analytics Vendors

OneSignal Features - Integrating OneSignal with any Analytics vendor

For Developers For Marketers

OneSignal supports tracking subscription and notification data when users subscribe and notifications are clicked on each platform, including sending this data to your analytics tool so that it can be analyzed in the context of your other user data.

Checkout Our Google Analytics Webinar!

Mobile Guide

Tracking Mobile Notification Received and Clicked Events

Received: Send an event to your analytics system from the SDKs NotificationReceived event handler when a notification is received. Keep in mind, this event only gets called if the app is open and in the foreground or background. It will not get called if the app has been swiped away.

Clicked: Send another event to your analytics system from the NotificationOpened or Action event handler when a notification is clicked.

Event
SDK Method
Details

Track Notification Received

Android - Method fired when the notifications is received.

iOS - Method fired when notification is received while app is in focus.




Track Notification Clicked

Method fired when the notification is clicked and opens the app.

Tracking Mobile Subscription Events

Send a subscription event to your analytics system from the SDKs PermissionObserver event handler when a user subscribes.

Event
SDK Method
Details

Track Subscription Event

Method fired when user changes permission status. Use to track:

  • Notification permission prompt shown (iOS)
  • The user accepting or declining the permission prompt (iOS)
  • Enabling/disabling notifications for your app in the App Settings and after returning to your app.

Web Push

Tracking Web Push Notification Clicks

By UTM Parameters

The easiest way to track notification clicks is to add UTM parameters to the end of the URL for the notification. Here's an overview on UTM parameter: http://blog.rafflecopter.com/2014/04/utm-parameters-best-practices/

When sending a notification, please pick a utm_source (Such as "onesignal"), a utm_medium (Such as "web-push" or "api" vs "automated" vs "dashboard"), and a utm_campaign parameter (Such as "promotional-offer-template-123"). Next, add these parameters to your url, like so:

https://yoursite.com/your-page?utm_source=onesignal&utm_medium=web-push&utm_campaign=promotional-offer-template-123

If you are having issues with UTM parameters, please see this article on common UTM parameter mistakes: https://penguininitiatives.com/common-utm-campaign-url-tracking-mistakes-to-avoid/

By Page JavaScript

You can use the addListenerForNotificationOpened event of the OneSignal Javascript SDK to detect when a user clicks a notification.

Add the your Analytics Tracking code to the head tags of your site, then add this code to the body tags of the page you are directing users upon clicking the notification. This will track the notification ID and OneSignal player ID

<script>
OneSignal.push(["addListenerForNotificationOpened", function(payload) {
  console.log("OneSignal Notification Clicked Paylaod:");
  console.log(payload);
  OneSignal.getUserId( function(userId) {
    console.log("OneSignal User ID:", userId);
    //Make a POST call to your analytics tool with the notification data and userId aka playerId
    
  });
}]);
</script>

Tracking Subscriptions

Permission Prompt Change Events

You can use the notificationPermissionChange event of the OneSignal Javascript SDK to detect when a user subscribes to notifications or unsubscribes from notifications on your site.

Add your Analytics Tracking code to your site, then add this code to the body tags of the pages users can subscribe. This will track the subscription change event and the OneSignal player ID.

OneSignal.push(function() {
    // Occurs when the user's subscription changes to a new value.
    OneSignal.on('notificationPermissionChange', function(permissionChange) {
      var currentPermission = permissionChange.to;
      console.log('New permission state:', currentPermission);
      OneSignal.getUserId( function(userId) {
        // Make a POST call to your analytics tool with the subscription data and userId aka playerId
      });
   });
});

This will create several event actions in your analytics tool when users opt-in or opt-out.
You can then use filtering options in your analytics tool to track by day, week, month, landing pages and browsers.

Tracking Impressions of the opt in request pop-up

You can use the permissionPromptDisplay method to send an event to your analytics tool from your page's code, like so:

OneSignal.push(function() {
  // Occurs when native browser prompt is shown
  OneSignal.on('permissionPromptDisplay', function() {
    console.log("The native prompt displayed");
    // Make a POST call to your analytics tool with the Prompt data
  });
});

This will create an event in your analytics tool that you can track and filter by day, week, month, landing pages and browsers.

Tracking Actual Subscription Change

You can use the subscriptionChange event to track when specific users subscribe or unsubscribe from web push.

OneSignal.push(function() {
  // Occurs when the user's subscription changes to a new value.
  OneSignal.on('subscriptionChange', function (isSubscribed) {
    console.log("The user's subscription state is now:", isSubscribed);
    OneSignal.getUserId( function(userId) {
      // Make a POST call to your analytics tool with the subscription data and userId aka playerId
    })
  });
});

Tracking Notification Receipts & Dismissals

Advanced Topic

We recommend sending this data to your analytics tool as well (or another analytics tool). However since your website may not be open when notifications are received, dismissed, and opened by a user, this should be done by using our Webhook support.


Other Analytics Vendors


OneSignal Features - Integrating OneSignal with any Analytics vendor

Suggested Edits are limited on API Reference Pages

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