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

Segments

Cohorts or Groups of users based on data collected and sent to OneSignal.

Segments give you the ability to group and target devices with more personalized and engaging messages. You can divide your subscriber base into specific audiences based on multiple Filter Types of data automatically tracked by the OneSignal SDK (like activity, country, language, etc.) along with custom data sent to OneSignal via Data Tags.

Segments are updated automatically once created. As users interact with your app or website, devices may be added-to or removed-from segments without any additional setup or tracking on your end.

Segments Quickview Video


Creating Segments

Guide on creating segments through the OneSignal dashboard. For details on creating segments through the API see Create Segments POST Call.

In Audience > Segments select New Segment.

Adding a Filter

All possible Filter Types shown in your dashboard may be combined to create specific segments. Not all platforms support each Filter Type and not all filters have the same options.

Select the Last Session filter for the last time a device visited your app or website.

Set this to be "greater than" 240 hours. This will tell us how many subscribed devices have not returned to the site or app in over 10 days.

AND Clauses

After adding your first filter, the Add filter button will create an "AND clause" which requires all devices to fit into all filters combined with "AND clauses".

Under "Last Session" select Add filter and select Last Session again.

Set this to be "less than" 264 hours.

When a device has not visited the site in over 240 hours (10 days) they will enter into this segment AND after 264 hours (11 days) they will be moved out of this segment.

OR Clauses

To combine multiple filters that do not depend on each other, click Add Or to separate groups of filters.

Select Add Or and select First Session "greater than" 72 hours.

Now, the segment contains all devices that "First Subscribed" over 72 hours ago (3 days) OR devices that have not been back to the site in over exactly 10 days.

Name the segment something memorable like 10 Days Inactive Or Over 3 Days New and select Create Segment.

Deleting Filters

Simply click on the 'X' next to a filter to delete it from a segment. Note that any time a filter is added or deleted, the audience count is updated.

Creating Advanced Segments

Creating Segments with Tags and Location data.


Deleting Segments

Deleting segments from Audience > Segments does not delete the users within the segment. It just deletes the segment from the view. To delete devices within a segment permanently, see Delete Users.

Note: You cannot delete segments that are used in Automated Messages or In-App Messages until you update or change this in the section.

Default Segment

The OneSignal Dashboard defaults to the "Subscribed Users" segment when sending messages. This can be changed by setting a "default segment".

A "default segment" will be the first segment selected when creating a message within the OneSignal Dashboard. This is to help both quickly target certain segments used frequently and help prevent mistakes if the segment is not changed before sending the message.


Paused and Active Segments

If a segment is paused when trying to target it, the notification will fail.

You can Pause and Resume segments from the 3-dot Options button.


Filter Types

Understanding the data used to create segments.

Filter TypeDescription
FIRST SESSIONMobile - The first date/time the user's device opened the app with OneSignal SDK active and valid network connection.
Web Push - The first date/time the user subscribed to your site.
LAST SESSIONThe most recent date/time the user's device communicated with OneSignal servers. Updated both when users arrive and leave app / website.
SESSION COUNTMobile- The number of times the user's device has opened your app.
Web Push - The number of times the user visited your website after not having the website open previously.
USAGE DURATIONThe total number of seconds the user's device has had your app open. Only accumulated for sessions that are longer than 60 seconds on mobile and 30 seconds on web. See How is usage duration calculated.
AMOUNT SPENTThe amount the user has spent on In-App Purchases
iOS, Android, Amazon - this data is available without additional work. See What kind of in-app Purchases are tracked.
Web Push - you must integrate in-app purchase as Data Tags and filter based on tag.
PURCHASED ITEMFilter by code of In-App Purchase item.
iOS, Android, Amazon - this data is available without additional work. See What kind of in-app Purchases are tracked.
Web Push - you must integrate in-app purchase as Data Tags and filter based on tag.
LANGUAGELanguage of user's device. See Language & Localization for possible codes.
APP VERSIONVersion of your app gathered from Android Studio versionCode in your App build.gradle and iOS uses Identity Version or CFBundleShortVersionString in Xcode.
DEVICE TYPEDevice operating system: Google Android, Huawei Android, iOS, Windows Phone, Chrome, Firefox, Safari, or Email
USER TAGRequires Data - Tags you have added to the user's device. See Data & Tags for more details.
LOCATIONRequires Data - Radius in meters from a particular geocoordinate (lat, long).
ROOTEDAndroid - whether devices is rooted.
SUBSCRIPTIONSDeprecating - iOS, Android, Windows Phone ONLY - Whether user is not subscribed to notifications from another app you have access to.
EMAILThe push notification record tied to a specific email set with our SDK setEmail method.
COUNTRYCountry the user's device was in the last time it communicated with OneSignal servers.
TEST USERSIncludes all test users that you have set up as a Test User.

FAQ

How do I add specific users to a Segment?

Because segments are created by filters, you will need to add Data Tags for each user you wish to be in a segment with the User Tag filter. See next question for options to add tags to users.

You can also target groups of devices by the User ID with our Create notification REST API.

How can I create a segment based on Player ID or External User ID?

Segments require a filter to group users. Player ID and External User ID are not filters, but you can add Data Tags to select devices based on these IDs using the following:

You can also target groups of devices by the User ID with our Create notification REST API.

How can I target Web Desktop vs Web Mobile Subscribers?

Unfortunately we do not provide a way to detect mobile-web subscribers vs desktop-web subscribers automatically at this time. However, you can set this up with Adding Data Tags and following this example guide with code.

What kind of in-app purchases are tracked and how can I import historical in-app purchases?

The OneSignal mobile SDKs will automatically track all previous in-app purchases as soon as the device opens the app with our SDK active, with the exception of 2 types:

1 - Previously bought "Consumable" in-app purchases. These are tracked with our SDK active but not previously bought without our SDK.

2 - Subscription based in-app purchases.

Android docs: https://developer.android.com/google/play/billing/billing_library_overview#Query

Are segment counts accurate?

Once you reach over 100,000 Total Users, segment counts begin to be estimated in order to keep the dashboard running quickly and smoothly. To get the most accurate numbers, see the Delivery stats for the message sent to that segment.

How is Usage Duration Calculated?

For Android and iOS if a user backgrounds the app we don't call on_focus to update the usage time unless we have tracked 60+ seconds of the app being in focus. It is under 60 seconds the time caries over. For Web, usage duration is tracked after 30 seconds.
Example:
User opens the app
Uses app for 30 seconds
Backgrounds the app
We do our 60 sec check, only have 30 sec so skip network call
User reopens app
Uses app for 45 seconds
Backgrounds the app
We do our 60 sec check, have 75 sec of unreported time
Make on_focus call reporting 75 seconds of usage

Updated about a month ago



Segments


Cohorts or Groups of users based on data collected and sent to OneSignal.

Suggested Edits are limited on API Reference Pages

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