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    Support

Using Data Tags

OneSignal Features - Data Tags

For Developers
For Marketers


If you haven't yet integrated tags into your OneSignal implementation, start here.

Tags are one of OneSignal’s most powerful features, allowing customers to store arbitrary data attributes on each user. Tags are available on all OneSignal accounts, and are a very popular feature among our customers.

Why Use Tags

Tags unlock three important features of OneSignal:

1. Improve user targeting by filtering in Segments

The most frequent use of tags by customers is filtering users by certain attributes. Popular types of tags include app activity, user account information, and demographics.

For instance, customers often check whether users have completed app onboarding, which allows them to send targeted messages to users that may have dropped off before understanding the app’s value proposition. Customers will also frequently store whether a user has a certain type of account or account privileges, such as if they’re a VIP, Premium User, etc. These attributes let customers send highly targeted messages to their most valuable users.

2. Personalize messages to users with Variable Substitution

Tags can be used to personalize messages with variable substitution. For example, customers that want to send a welcome message may prefer to use the user’s name, rather than a more generic message. This is made possible by sending OneSignal the user’s name as a tag.

To learn more about variable substitution, take a look at OneSignal Tag & Variable Substitution Documentation and read our blog post.

3. Build helpful linkages to internal CRM systems

Many customers use internal CRMs or other systems to link their user records with OneSignal user records. This allows customers to get a deeper sense of who their customers are and perform offline analytics. These linkages are made by tagging a OneSignal user with the internal user ID. To learn more, read more about integrating with your Internal Database & CRM.

How to Use Tags

Tags are visible from All Users, and may be used to filter users within Segments.

Tags may only be added to users via the SDK or API. They cannot be added via the dashboard.

1. Create a Segment using Tags filter

To target specific users with tags, you must first Create or Edit a Segment.

  1. Add the User Tag filter, typing in the tag key you wish to match

  2. Select the appropriate operator (greater than, less than, equal to)

  3. Enter in the tag value you wish to match

Note that the operators greater than and less than only work on values that are numeric. Any users with non-numeric values for your chosen key will be ignored when using these operators.

Example of Numeric Operators

You wish to create a segment of users that have opened the app at least once. You have three users, with the following tags:

user1 - {opened_app: yes}
user2 - {opened_app: 2}
user3 - {opened_app: 0}

If you add the filter opened_app greater than 0, the following will be part of your segment:
user1 - excluded (because the value is not set to a number)
user2 - included
user3 - excluded (the value is not greater than 0)

2. Send Message to Segment

Now that you've created your segment matching at least one user, you can send a notification targeting this segment using this option:

Click the "X" button to remove the segment.

If you get an error saying "The selected segments does not have any users", go back to your Segments page and check the filter conditions. Remember they are ANDed together and not ORed together. Make sure the segment includes at least one user.

You can add segments to exclude as well.

If you exclude a segment all the users in the excluded segment that match users in the targeted segment will NOT get notifications.


You've successfully sent a targeted message to your users with data tags.

Using Data Tags

OneSignal Features - Data Tags

For Developers
For Marketers