User-based segmentation

Use user-based segmentation to build segments of Users instead of Subscriptions. When a user enters a segment, the user brings all of their Subscriptions, so the same segment works for push, email, SMS, and in-app messages.

User-based segmentation is coming soon and is not available yet. This page explains how it works so you can prepare before it’s enabled for your app. Functionality may change before release. For how segments work today, see Segments.

Subscription-based vs user-based segments

Compare the two models by what a segment contains. OneSignal stores data in two layers:

A User is one person in your app. User-level data includes Tags, country, language, and sessions.
A Subscription is one place a user receives messages, such as an email address, a phone number, or an app on a device. Each Subscription has its own subscription status, device type, and app version.

	Subscription-based segments	User-based segments
What the segment contains	Only the Subscriptions that match the filters	Users, each with all of their Subscriptions
Channels the segment works on	Only the channels of the matching Subscriptions. A segment built with an email filter can only reach users by email.	Every channel. The message’s channel decides which Subscriptions receive it.
Counts in the dashboard	Subscriptions	Users, with a breakdown by channel

When your app joins early access, OneSignal converts every existing segment to a user-based segment automatically. You do not need to recreate your segments.

How OneSignal evaluates a user-based segment

OneSignal adds a user to a segment when at least one of the user’s Subscriptions matches the segment’s filters and the user has at least one subscribed Subscription. A user whose Subscriptions are all unsubscribed does not enter the segment. OneSignal applies these rules:

User-level filters check the user. Device-level filters check the Subscription. Filters such as Tags, country, language, and sessions are checked against the user who owns the Subscription. Device Type and App Version are checked against the Subscription itself.
Filters joined by AND must match the same Subscription. Within one filter group, a single Subscription must satisfy every filter.
Filter groups joined by OR are evaluated independently. A user enters the segment if any group matches.
App Version must be paired with Device Type. You cannot use App Version on its own. In the segment editor, App Version is attached to a Device Type filter, and OneSignal checks both against the same Subscription. For example: Device Type is iOS AND App Version greater than 2.

Segment editor with a Device Type is iOS filter and an attached App Version greater than 0.41 filter, showing 34 subscribed users of 140 total and a channel breakdown for push, email, and SMS — A filter group pairing Device Type with App Version

In the example above, the segment filters on iOS, yet the channel breakdown still shows subscribed email and SMS users. Those users have an iOS Subscription that matches, so they enter the segment with all of their Subscriptions.

How messages are delivered

Think of delivery in two steps. The segment decides which users are in the audience. The message decides which of those users’ Subscriptions receive it.

The channel always narrows delivery. An email sent to a user-based segment goes only to email Subscriptions. An SMS goes only to SMS Subscriptions. A push notification goes only to push Subscriptions.
Optional Subscription filters narrow push and in-app messages further. Subscription filters let you choose which platforms and app versions receive the message.

Without Subscription filters, a push notification goes to every push Subscription that each user in the segment has. A segment defined by Device Type is iOS still sends push to those users’ Android and web push Subscriptions. To reach only matching devices, add the matching Subscription filters when you send.

Subscription filters

Use Subscription filters to send a push or in-app message to specific platforms and app versions. Subscription filters are optional settings on the message screens. Leave them unchanged to send to every Subscription on the message’s channel.

Push
In-app messages

Platform: Under Send to these platforms, select the platforms that should receive the message.
App version: Expand <Platform> settings (for example, Apple iOS settings). Under Delivery settings, use Send to a specific app version to choose an operator (such as greater than or is) and a version.

A platform in Subscription filters can cover more than one device type. For example, Web (Chrome, Safari, Firefox) covers web push Subscriptions in all three browsers. The push platforms are Apple iOS, Google Android, Huawei Android, Windows, Apple macOS, Web (Chrome, Safari, Firefox), and Google Chrome Apps & Extensions. Email and SMS messages do not need Subscription filters. The channel already selects the right Subscriptions.

Subscription filters are available in the dashboard once user-based segmentation is enabled for your app. In the Create message API, they apply to push notifications only. See How do I set Subscription filters in the API?.

Examples

These examples use four users. All of their Subscriptions are subscribed.

User	Subscriptions	Tags	Language	Country
Tom	Email, SMS, iOS (v1.4), Android (v1.2)	paid: yes, color: green	English	US
Bob	Email	paid: no, color: green	Spanish	US
Alice	SMS, iOS (v1.3)	paid: yes, color: red	English	CA
Riley	Android (v1.3)	paid: no, color: red	French	CA

Segment A: users with an email Subscription

Filters: Device Type is Email

Subscription-based: Tom’s and Bob’s email Subscriptions enter. The segment can only be used for email.
User-based: Tom and Bob enter with all of their Subscriptions. The segment works on every channel: email reaches Tom and Bob, and SMS and push reach Tom.

Segment B: paid users with an email Subscription

Filters: Device Type is Email AND paid = yes

Subscription-based: Only Tom’s email Subscription enters.
User-based: Tom enters with all four of his Subscriptions.

Segment C: paid users on iOS app version 1.4 or later

Filters: Device Type is iOS AND App Version greater than 1.3 AND paid = yes

Subscription-based: Only Tom’s iOS v1.4 Subscription enters.
User-based: Tom enters with all four of his Subscriptions.

When you send a push notification to this segment:

Without Subscription filters: The push goes to both of Tom’s devices, iOS v1.4 and Android v1.2.
With Subscription filters (platform Apple iOS, app version greater than 1.3): The push goes only to Tom’s iOS v1.4 device.

Segment D: filters in a group must match the same Subscription

Filters: Device Type is iOS AND App Version less than 1.4

Alice enters, because her iOS Subscription is v1.3.
Tom does not enter. His iOS Subscription is v1.4, and his v1.2 Subscription is Android. None of Tom’s Subscriptions matches both filters.

Segment E: users with an email or SMS Subscription

Filters: Device Type is any of Email, SMS

Tom, Bob, and Alice enter, because each has an email Subscription, an SMS Subscription, or both. Each enters with all of their Subscriptions.

What changes when your app joins early access

All existing segments become user-based

OneSignal converts every segment in your app to a user-based segment. Filters stay the same. Membership now follows the evaluation rules above.

Segment counts show users

The Segments page shows counts of users instead of Subscriptions:

Users: The number of users who match the segment criteria and are subscribed to at least one channel.
Push, Email, and SMS / RCS: The number of users in the segment who are reachable on each channel.

A user with Subscriptions on several channels is counted in each of those channel columns. The channel columns can add up to more than the Users column.

Segments page listing segments with Users, Push, Email, and SMS / RCS count columns — User counts on the Segments page

In the segment editor, the audience count shows subscribed users out of the total users in the segment. The Channel breakdown switches between Users and Subscriptions, and each filter group shows its own user count.

Filter the Users list by segment

On Audience > Users & subscriptions, the Users tab lets you filter the list by segment. Start typing a segment name in the segment filter and select the segment to see the users in it.

Review push and in-app messages that target device filters

If a segment filters on Device Type or App Version, messages sent to it can reach more devices than before. See Segment C. For each push or in-app message that should reach only those devices, add matching Subscription filters when you send.

Segment combination rules stay the same

The rules for including and excluding segments with message event or custom event filters do not change. See Can I combine custom event or message event segments with other segments?

FAQ

Will my existing segments change?

Your segments keep the same names and filters. Membership changes from Subscriptions to users: each user who matches enters with all of their Subscriptions, and counts show users instead of Subscriptions.

Does user-based segmentation change Journeys?

No. Journeys have always worked with users: when you use a segment in a Journey, OneSignal enters each user in the segment, not individual Subscriptions. User-based segmentation brings segments in line with Journeys, so a segment describes a group of users whether you send a message to it or start a Journey with it.

Why did my push notification reach more devices than before?

In a user-based segment, each user brings all of their push Subscriptions. Without Subscription filters, a push notification goes to every push Subscription those users have. To reach only certain devices, select the platforms under Send to these platforms and set Send to a specific app version when you need a version limit. In the API, set the platform parameters and add subscription_filters to limit the app version.

How do I send a push notification only to iOS devices?

Under Send to these platforms, select only Apple iOS. To limit the app version, expand Apple iOS settings and set Send to a specific app version under Delivery settings. In the API, set isIos to true, and add subscription_filters with type set to iOSPush to limit the app version. See How do I set Subscription filters in the API?.

Can I use App Version without Device Type in a segment?

No. In a user-based segment, App Version must be attached to a Device Type filter, and both are checked against the same Subscription.

Does a user with only unsubscribed Subscriptions enter a segment?

No. A user enters a user-based segment only when at least one of the user’s Subscriptions matches the filters and the user has at least one subscribed Subscription.

Is user-based segmentation available now?

No. User-based segmentation is coming soon. OneSignal is publishing this documentation early so you can learn how it works before it’s enabled for your app. To register interest in early access, contact support@onesignal.com.

How do I set Subscription filters in the API?

Use the platform parameters (such as isIos) to choose platforms, and subscription_filters to limit the app version, in the Create message API. These map to the two Subscription filters settings: the platform and the app version. subscription_filters works only for push notifications, and the only supported field is app_version. For in-app messages, set Show on a specific app version in the dashboard. Email and SMS do not use Subscription filters, because the channel already selects those Subscriptions. Platform. The platform parameters are the API equivalent of Send to these platforms. By default, a Create message request sends to every push platform configured for the app. Set a platform parameter to choose which platforms receive the push:

Apple iOS: isIos
Google Android: isAndroid
Huawei Android: isHuawei
Windows: isWP_WNS
Apple macOS: isMacOSX
Web (Chrome, Safari, Firefox): isAnyWeb
Google Chrome Apps & Extensions: isChrome
Amazon: isAdm

App version. subscription_filters is the API equivalent of Send to a specific app version. It accepts an app version only for Apple iOS (iOSPush), Google Android (AndroidPush), Huawei Android (HuaweiPush), and Amazon (AmazonPush). You can’t limit the app version for Windows, Apple macOS, Web, or Google Chrome Apps & Extensions. The relation values match the dashboard operators: = (is), gt (greater than), and lt (less than). The following request sends to Apple iOS on app versions greater than 1.3, the same limit as Segment C:

{
  "isIos": true,
  "subscription_filters": [
    {
      "field": "app_version",
      "relation": "gt",
      "value": "1.3",
      "type": "iOSPush"
    }
  ]
}

To limit one platform to a version range, put gt and lt in the same group. A group holds at most two entries, one gt and one lt, and each subscription type can appear in only one group. An entry with no group applies on its own.

{
  "isAndroid": true,
  "subscription_filters": [
    {
      "field": "app_version",
      "relation": "gt",
      "value": "1500",
      "type": "AndroidPush",
      "group": 1
    },
    {
      "field": "app_version",
      "relation": "lt",
      "value": "3000",
      "type": "AndroidPush",
      "group": 1
    }
  ]
}

Omit subscription_filters to send to every app version on the selected platforms. subscription_filters does not change who is in the segment. The filters parameter still decides which users match, and you can send both in one request. The API accepts subscription_filters only when user-based segmentation is enabled for your app. Otherwise, it returns subscription_filters is not enabled for this app.

Segments

Create, filter, and manage segments.

Users

How OneSignal identifies users across devices and channels.

Subscriptions

The push, email, and SMS records that belong to each user.

Target outdated app versions

Use App Version and Device Type filters to reach users on older builds.

Journeys overview

Trigger automated workflows from segment membership.

First steps & settings

Message channels

Journeys

OneSignal AI

Audience & events

Analytics & Integrations

Privacy & Security

User-based segmentation

Subscription-based vs user-based segments

How OneSignal evaluates a user-based segment

How messages are delivered

Subscription filters

Examples

What changes when your app joins early access

All existing segments become user-based

Segment counts show users

Filter the Users list by segment

Review push and in-app messages that target device filters

Segment combination rules stay the same

FAQ

Will my existing segments change?

Does user-based segmentation change Journeys?

Why did my push notification reach more devices than before?

How do I send a push notification only to iOS devices?

Can I use App Version without Device Type in a segment?

Does a user with only unsubscribed Subscriptions enter a segment?

Is user-based segmentation available now?

How do I set Subscription filters in the API?

Segments

Users

Subscriptions

Target outdated app versions

Journeys overview

​Subscription-based vs user-based segments

​How OneSignal evaluates a user-based segment

​How messages are delivered

​Subscription filters

​Examples

​What changes when your app joins early access

​All existing segments become user-based

​Segment counts show users

​Filter the Users list by segment

​Review push and in-app messages that target device filters

​Segment combination rules stay the same

​FAQ

​Will my existing segments change?

​Does user-based segmentation change Journeys?

​Why did my push notification reach more devices than before?

​How do I send a push notification only to iOS devices?

​Can I use App Version without Device Type in a segment?

​Does a user with only unsubscribed Subscriptions enter a segment?

​Is user-based segmentation available now?

​How do I set Subscription filters in the API?

​Related pages

Segments

Users

Subscriptions

Target outdated app versions

Journeys overview

Subscription-based vs user-based segments

How OneSignal evaluates a user-based segment

How messages are delivered

Subscription filters

Examples

What changes when your app joins early access

All existing segments become user-based

Segment counts show users

Filter the Users list by segment

Review push and in-app messages that target device filters

Segment combination rules stay the same

FAQ

Will my existing segments change?

Does user-based segmentation change Journeys?

Why did my push notification reach more devices than before?

How do I send a push notification only to iOS devices?

Can I use App Version without Device Type in a segment?

Does a user with only unsubscribed Subscriptions enter a segment?

Is user-based segmentation available now?

How do I set Subscription filters in the API?

Related pages