Custom Outcomes
Track events and actions within your app or site resulting from push notifications and in-apps from OneSignal.
OneSignal allows you to track various Outcomes (events or actions) resulting from notifications that you send.
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).
Custom Outcomes is a Professional and Enterprise feature.
Custom Outcomes are available to customers on the Professional or Enterprise plan. To learn more, read about our pricing.
Implementing Outcomes
In your app, add a line of code where you want an Outcome to be triggered (e.g. on "add to cart" button or "upgrade subscription" button).
There are three methods for custom Outcome types:
Method | Description |
---|---|
addOutcome | Increases the "Count" by 1 and will be counted each time sent. |
addOutcomeWithValue Web: addOutcome | Increases the "Count" by 1 and the "Sum" by the value. Will be counted each time sent. |
addUniqueOutcome | 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. |
Missed Outcomes
Failures for Outcomes are cached on the device and re-attempted on the next OneSignal init.
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) |
One of Outcomes' most powerful features is the ability to store numeric values as a sum with the firing of each Outcome.
Note: Outcomes with values always round to the nearest whole number.
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 for any given push message.
// "Purchase" button pressed in the app
...
OneSignal.Session.addOutcomeWithValue("Purchase", 18.76);
// "Purchase" button pressed in the app
...
[OneSignal.Session addOutcomeWithValue:@"Purchase" value:18.76]
//Purchase Button pressed on site
OneSignal.Session.addOutcome("Purchase", 20.20);
let value = "20.20"//you supply the value
OneSignal.Session.addOutcome(withValue: "Purchase", value: NSNumber(value:value), onSuccess: {outcomeSent in
print("outcome sent: \(outcomeSent!.name) with random value: \(value)" )
})
//Send an outcome
OneSignal.Session.AddOutcome("outcomeName");
//Send a unique outcome
OneSignal.Session.AddUniqueOutcome("uniqueOutcomeName");
//Send an outcome with a float value
OneSignal.Session.AddOutcomeWithValue("outcomeWithVal", 4.2f);
Use Cases
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.Session.addOutcomeWithValue("Purchase", 18.76);
[OneSignal.Session addOutcomeWithValue:@"Purchase" value:18.76]
OneSignal.Session.addOutcome("Purchase", 18.76);
OneSignal.Session.AddOutcomeWithValue("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.Session.addUniqueOutcome("Swipe");
[OneSignal.Session addUniqueOutcome:@"Swipe"]
//OUTCOME WITH UNIQUE VALUES COMING SOON TO WEB
OneSignal.Session.addOutcome("my_outcome_event");
OneSignal.Session.AddUniqueOutcome("swipe");
Pushes Clicked By Language
Within the Notification Opened/Clicked listener methods 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.Session.addOutcome(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.Session.addOutcome(languageCode);
}
}
var language = navigator.language
OneSignal.Session.addOutcome(language);
Pushes Clicked By Operating System and Browser
Within the Notification Opened/Clicked listener methods 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.Session.sendOutcome(os);
OneSignal.Session.sendOutcome(browserType);
}]);
FAQ
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.
What channels support custom outcomes?
Currently custom outcomes be added to actions on Push and In-App Messages only.
Outcomes sent through In-App messages will show as "Unattributed" and will set a tag on the device in format:
outcome name : true
.
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.
What happens if a device is offline?
Data for fired outcomes are queued to be sent to OneSignal once the device is online again.
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.
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 6 days ago