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

OneSignal features - Segmenting your users
Learn how to group your users by 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 total subscriber base into specific audiences based on Filter Types of data automatically tracked by the OneSignal SDK (like activity, country, language, etc.) along with custom data you send to OneSignal via Data Tags.

Segments are updated automatically once you set them. 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.

For details on creating segments through our API see Create Segments POST Call.

Segments Quickview Video


Filter Types

Understanding the data used to create segments.

Filter Type

Description

FIRST SESSION

Mobile - 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 SESSION

The most recent date/time the user's device communicated with OneSignal servers. Updated both when users arrive and leave app / website.

SESSION COUNT

Mobile- 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 DURATION

The 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 SPENT

The 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 ITEM

Filter 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.

LANGUAGE

Language of user's device. See Language & Localization for possible codes.

APP VERSION

Version of your app gathered from Android Studio versionCode in your App build.gradle and iOS uses Identity Version or CFBundleShortVersionString in Xcode.

DEVICE TYPE

Device operating system: Google Android, Huawei Android, iOS, Windows Phone, Chrome, Firefox, Safari, or Email

USER TAG

Requires Data - Tags you have added to the user's device. See Data & Tags for more details.

LOCATION

Requires Data - Radius in meters from a particular geocoordinate (lat, long).

ROOTED

Android - whether devices is rooted.

SUBSCRIPTIONS

Deprecating - iOS, Android, Windows Phone ONLY - Whether user is not subscribed to notifications from another app you have access to.

EMAIL

The push notification record tied to a specific email set with our SDK setEmail method.

COUNTRY

Country the user's device was in the last time it communicated with OneSignal servers.

TEST USERS

Includes all test users that you have set up as a Test User.


Creating Segments

Guide on creating segments through the OneSignal dashboard.

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.

For instance, the SESSION COUNT filter type requires both the operator (Greater than / less than / equal to / not equal to) and the number of sessions.

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".

For instance, you may have a SESSION COUNT filter of greater than 20 sessions, and a FIRST SESSION filter of after 72 hours. In this case, users must have both logged into your app more than 20 times AND started using your app more than 72 hours ago.

OR Clauses

If you want to add filters without having them combined with other filters, you can instead click 'ADD OR' to separate groups of filters.

For instance, you may want to check engaged users by either 20+ sessions and last login less than 72 hours ago, OR 5+ sessions and last login less than 24 hours ago.

Deleting Filters And Filter Counts

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.

See our below Segments FAQ for more details on Counts.

Deleting Segments

If you ever need to delete a segment, just click on the segment from the segment list, and click the DELETE SEGMENT button in the bottom left corner of the Segment Editor. This does not delete the user records of the segment. 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

Once a segment has been created, it can be Set As Default which will be used as the first or default option when Sending Messages through the dashboard.

When you first create an app, the Subscribed Users segment will be default. If you wish to delete a segment that is "set as default", assign a different segment as default before deleting it.


Creating Advanced Segments

Creating Segments with Tags and Location data.


Paused and Active Segments

Free OneSignal Apps can only contain 6 Active segments at a time if you have over 30,000 Subscribers.

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

You can "Pause" and "Set Live" segments from within the Segment Editor.

In order to set a PAUSED segment ACTIVE, you need to pause another ACTIVE segment first so you only have 6 segments active at a time.

Select the ACTIVE segment and click the "Pause" Button and confirm with the "Pause Segment" button.

Then select the PAUSED segment you wish to activate and click "Set Live"

The segment will immediately become ACTIVE and can be used for notification targeting.


FAQ

How do I add specific users to a Segment?

Because segments are created by filters, you will need to add a tag for each user you wish to be in a segment. Then, when creating the segment, add a "User tag" filter to your segment matching the same tag.

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

Segments require a filter to group users. Unfortunately Player ID and External User ID are not filters, but you can add tags to select devices based on the Player ID or External User ID using our Importing User Attributes feature.

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

How can I view all the users in a segment?

You can view and export all users in a segment by going to the 'Audience' tab, then 'All Users', and then selecting the segment of interest from the drop-down menu on the left. Detailed instructions are here: Exporting Data.

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


OneSignal features - Segmenting your users
Learn how to group your users by 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.