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

Outcomes

Track events and actions within your app or site resulting from push notifications from OneSignal.

As a Paid Plan Feature OneSignal allows you to track various Outcomes (events or actions) resulting from push notifications.

This includes tracking things you care about like event counts (e.g. how many users purchased a product), sums (useful for tracking revenue), or unique events (counted only once).

๐Ÿ“˜

Webinar Video

Watch our latest Outcomes webinar here.

Outcome Types

OneSignal provides 2 default Outcomes: Notification Clicks and Session Duration. You can add up to 100 more different outcomes to be tracked.

Outcome

Description

Details

Notification Clicks

Tracks number of clicks/opens on a push notification.

A click is generated when the user presses the notification which triggers the app or site to open and removes the notification from the device.

Clicks always measured with direct attribution.

Session Duration

COUNT: Number of sessions that resulted from a push notification.
SUM: Cumulative session time of all sessions resulting from a push notification (in seconds).

A new session is created when a user clicks a notification resulting in the app opening.

If a notification is clicked but app is already open, then no new session is created.

Custom Outcome

Any custom outcome such as purchase amount, action taken by the user, or any other outcome of interest.

This is set with code.

Limit of 100 custom outcomes


Attributions

Outcomes can be attributed to a notification directly from a click or influenced by a notification received. This depends on if a session is created by the notification click which opens the app or website from being closed. If a notification is not clicked or received when the outcome is triggered it is an unattributed outcome.

If a user has the app or site open and clicks the notification, a session is not created and the Outcome will be influenced. Similarly, if up to 10 notifications are sent and never clicked, but the user performs the Outcome within the specified Attribution Window (default 24 hours), then up to all 10 notifications will track the outcome as influenced.

Clicks (count) will always be directly attributed to a notification and do not rely on a session.

Attribution

Description

DIRECT

The Outcome happened during a session that was created due to a clicked push.

INFLUENCED

The Outcome was registered within the Attribution Window (default 24 hours) of the push but didnโ€™t occur during a session directly initiated from a push.

Note: Only the 10 most recently sent notifications (per device) get influenced attribution

UNATTRIBUTED

The Outcome was registered outside of a message click and the Attribution Window. It therefore is not associated with any specific message.

TOTAL

Sum of Direct + Influenced Outcomes when viewing the Message Reports.

Sum of Direct + Influenced + Unattributed when viewing the Delivery > Outcomes table.

Direct Opens

The push notification was clicked, opened the app or website from a new session (app or website not open in the past 30 seconds) and the user performed the action which triggered the Outcome.

Influenced Opens

Inside Settings > Analytics

Outcomes performed when a user receives a push within the Attribution Window but does not click the push. Instead they open the app or website directly.

Attribution Window - the amount of time influenced Outcomes can be attributed to a notification. You can set 15 minutes, 1 hour and 24 hours which is default.

If you keep the Attribution Window to the default 24 hour maximum, any Outcome Types except Clicks will show in the Outcomes table for up to 10 most recent notifications.

For example:

  • Attribution Window set to 24 hours and you send 15 notifications that day.
  • UserA does not click any notifications but opens the app.
    Then the last 10 most recent notifications will have updated Session Duration count and sum.
    If you also specified a Custom Outcome, like the user buys a product, then the last 10 notifications will also show that Custom Outcome in the Outcomes Table.

Count Vs Sum

For Session Duration and Custom Outcomes, there are two metrics available: count and sum

Metric

Description

COUNT

The frequency of the Outcome (how many times it occurred)

SUM

The sum of all Outcome values (only available for Outcomes that register values)


Outcome Values

One of Outcomes' most powerful features is the ability to store numeric values in the Sum Row with the firing of each Outcome.

For example, you may want to track how much revenue can be attributed to a push campaign. In this example, you can register a monetary value with a Custom Outcome such as a purchase. Simply pass an outcome name with the number you wish to associate it with. You can then see these data in the Message Report page for any given push notification.

// "Purchase" button pressed in the app
   ...
   OneSignal.sendOutcomeWithValue("Purchase", 18.76);
// "Purchase" button pressed in the app
   ...
   [OneSignal sendOutcomeWithValue:@"Purchase" value:18.76]
//Purchase Button pressed on site
OneSignal.sendOutcome("Purchase", 20.20);

Session Duration

Sessions are created when the user opens the app or website from previously being closed.

A direct session is registered when the user opens the app or site from a push.
An influenced session is registered when the user opens the app within the Attribution Window (default 24 hours).

Sessions become apparent in Message Reports after the session is finished (user leaves app or site).

If you send up to 10 notifications and the user visits the app or website within the Attribution Window, then all 10 notifications will be counted towards Influenced Session Duration count and sum.


Implementing Outcomes

Default Outcomes

Update to the latest version of the SDK. Free users automatically get clicks right out of the box. Paid plan users will get clicks and sessions.

Custom Outcomes

Add a line of code where you want an Outcome to fire (e.g. on "add to cart" button or "upgrade subscription" button).

There are three methods for custom Outcome types:

Method

Description

sendOutcome

Increases the "Count" by 1 and will be counted each time sent.

sendOutcomeWithValue
Web: sendOutcome

Increases the "Count" by 1 and the "Sum" by the value. Will be counted each time sent.

sendUniqueOutcome

Increases "Count" by 1 only once. This can only be attributed to a single notification. If the method is called outside of an attribution window, it will be unattributed until a new session occurs.

๐Ÿ“˜

Example Outcomes Code

See below Outcomes Examples for more on implementation.

๐Ÿšง

Missed Outcomes

Failures for Outcomes are cached on the device and re-attempted on the next OneSignal init.


Reports

Each Message Report contains all Outcome Statistics related to that notification as well as information such as delivery numbers, click-through rate, and influenced opens.

You can also view a cumulative graph of all outcomes over the past 30 days in Delivery > Outcomes.

Outcomes can be viewed as a graph...

or as a table:


Examples

E-Commerce Site

Online stores can use OneSignal push notifications to drive users back to abandoned carts, flash sales, promotions, and more. With Outcomes, store owners can now easily correlate push notifications to user actions such as an add-to-cart, purchase, or coupon redeemed. For purchases, outcomes go even further than simple counts and can track purchase amounts. This allows site owners to easily view the sum total of revenue generated from individual pushes.

OneSignal.sendOutcomeWithValue("Purchase", 18.76);
[OneSignal sendOutcomeWithValue:@"Purchase" value:18.76]
OneSignal.sendOutcome("Purchase", 18.76);

Dating app

Online dating apps may want to re-engage users by using a push to notify them of a match, a new like, or simply to get them swiping. By using Outcomes, a dating app developer can see whether a push notification led to a user event such as initiating a chat with a match or a 34-second swipe session. These data can then be used to refine notification and targeting strategies.

In the following example, we want to track whether a user started swiping dating profiles after a push. Since we wouldn't want to count every swipe as a conversion, we use sendUniqueOutcome

This "Swipe" outcome will only be attributed once to the push that triggered it. Examples:

  • If the user clicked the push and performed the action which called this method, it will be a direct attribution.
  • If user received the push but did not click it and performed the action within in the attribution window, it will be an influenced attribution. Even if they later click the same push and performed the action again, it will still only be influenced.
  • If user performs method outside of an attribution window, it will be unattributed once per session.
OneSignal.sendUniqueOutcome("Swipe");
[OneSignal sendUniqueOutcome:@"Swipe"]
//OUTCOME WITH UNIQUE VALUES COMING SOON TO WEB
OneSignal.sendOutcome("my_outcome_event");

Pushes Clicked By Language

Within the Notification Opened/Clicked Event of our SDK, you can setup Outcomes to increment how many devices clicked a push by their set language. This will require some native code to detect the language of the device, but you can then pass that language into the Outcome like so:

public void notificationOpened(OSNotificationOpenResult result) {
  String languageCode = Locale.getDefault().getLanguage();
  System.out.println("languageCode " + languageCode);
  OneSignal.sendOutcome(languageCode);
}
let notificationOpenedBlock: OSHandleNotificationActionBlock = { result in
  // This block gets called when the user reacts to a notification received
  if let languageCode = Locale.current.languageCode {
      print ("languageCode: " + languageCode);
      OneSignal.sendOutcome(languageCode);
}
}
var language = navigator.language
OneSignal.sendOutcome(language);

Pushes Clicked By Operating System and Browser

Within the Notification Opened/Clicked Event of our SDK, you can setup Outcomes to increment which platform's specifically were clicked. This is generic for iOS and Android as you can set OneSignal.sendOutcome("iOS") or OneSignal.sendOutcome("Android") in your mobile app's click handler, but if you want to track web push platforms as well, you can use this for example:

// Example taken from Stackoverflow: https://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript
var os = "Unknown OS";
if (navigator.userAgent.indexOf("Win") != -1) os = "Windows";
if (navigator.userAgent.indexOf("Mac") != -1) os = "Macintosh";
if (navigator.userAgent.indexOf("Linux") != -1) os = "Linux";
if (navigator.userAgent.indexOf("Android") != -1) os = "Android";
if (navigator.userAgent.indexOf("like Mac") != -1) os = "iOS";
console.log('Your os: ' + os);

var browserType = "Unknown Browser Type";
if (navigator.userAgent.indexOf("Safari") != -1) browserType = "Safari";
if (navigator.userAgent.indexOf("Chrome") != -1) browserType = "Chrome";
if (navigator.userAgent.indexOf("OPR") != -1) browserType = "Opera";
if (navigator.userAgent.indexOf("Firefox") != -1) browserType = "Firefox";
console.log('Your Browser: ' + browserType);

OneSignal.push(["addListenerForNotificationOpened", function(data) {
  OneSignal.sendOutcome(os);
  OneSignal.sendOutcome(browserType);
}]);

FAQ

What platforms are supported?

Make sure you have the minimum SDK version or higher installed. We recommend using the latest version of the OneSignal SDK.

What happens if a device is offline?

Data for fired outcomes are queued to be sent to OneSignal once the device is online again.

How long is outcome data stored?

  • Notifications sent from the dashboard keep their Outcome data forever.
  • Notifications sent via the API have a 30-day retention of outcomes before being purged.

Can I export outcomes?

You can export a set of outcomes or all outcomes as a CSV. We also provide API access to outcomes for an individual notification or for all the notifications.

Can I store strings as values in Custom Outcomes?

This is not supported

If a user backgrounds the app after clicking a notification and then comes back to it, firing an Outcome, is it counted direct or influenced?

As long as the user returns to the app within 30 seconds after backgrounding it, the session will still be considered the original session and will get direct attribution.

Do outcomes work with email or In-App Messages?

Currently outcomes only work with push notifications.

When does the new Attribution Window take affect?

If you change the attribution window from 24 hours to 1 hour for example, then the 1 hour window will take affect on a per-device basis once each device opens the app from a brand new session. This new session is created after 30 seconds of being outside the app.

Why is Safari not logging outcomes?

Outcomes for web requires the use of service workers to track outcome events. Since Safari does not implement Service Workers in the same way as Chromium based browsers, it will not track outcomes as Direct or Influenced, but will be tracked as Unattributed.

Why do sessions not match with other analytics?

OneSignal only counts a session after the user has left the app for over 30 seconds. If you close the app or website and return to it within 30 seconds, it will not be a new session.

For instance, Apple's analytics tracks the session as the number of times the app has been used for at least two seconds. If the app is in the background and is later used again, that counts as another session.

Updated about a month ago



Outcomes


Track events and actions within your app or site resulting from push notifications from OneSignal.

Suggested Edits are limited on API Reference Pages

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