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

Add Data Tags

How to add user data tags to your OneSignal implementation for Web Push and Mobile.

Overview

OneSignal supports tagging users with simple string data. Tags unlock three important features of OneSignal:

  1. Targeting notifications to specific users or groups using Segments

  2. Personalizing messages to users with Variable Substitution

  3. Integrating with your Internal Database & CRM for analytics and tracking


Implementation

Video Setup Guides!

For more visual people, we have created a tagging setup guide:

Tagging Guide
Example code from video

Once you've integrated OneSignal in your app or website, implementing tags is very straightforward - simply use the sendTag or sendTags methods to tag your users with a key-value pair at any time. You may also get and delete tags with other methods. To learn more and to check out code examples, dive into the SDK reference for your particular app or website:

Tagging Examples

Many apps and sites use custom userIds to track their users. You can add your own custom userIds to each device record with the following examples.

OneSignal.push(function() {
  OneSignal.sendTags({
    userId: 'example_userId_123'
  }).then(function(tagsSent) {
    // Callback called when tags have finished sending
    console.log(tagsSent);   
  });
});

Recommended Tags to Send

The OneSignal SDK sends some data automatically for use in filtering. For all other needs, customers should use tags. The tags we most frequently see customers get use out of are below, and we recommend using the following key names to simplify your implementation.

Note: Your app must already collect this information in order to send it as tags; if your app does not collect data from a particular key below, don't worry about sending it.

Account-Related Data

Adding account-related tags are a great way to target messages to groups of users based on properties of their account such as cohort, or to link user data to your internal database / CRM.

Key
Definition

user_id

your app's user id, used to connect user data to your internal database / CRM for additional analysis. Learn more

user_type

type or tier of account users have (e.g. free, premium, vip, admin)

user_classifier

additional classifiers about a user (e.g. cohort, pirate, cheater, valid account, etc)

user_privileges

Some customers like to track user privileges in addition to type (e.g. administrator, early access, normal, guest)

user_id_[service]

Some customers store a user id for third party services such as analytics platforms. We recommend naming these keys based on the service name, such as user_id_unreal, user_id_openid, user_id_segmentio

User Names & Preferences

Using a user’s name to personalize notifications is a great way to boost engagement. Just create a key for their name like the ones below and use Variable Substitution when crafting your messages. These data tags are available for use in Email Messaging, so we recommend using these exact key names.

Key
Definition

real_name

user’s full real name

first_name

user’s first name

last_name

user’s last name

user_name

name that users give themselves; often not a real name (e.g. PokeCatcher22)

salutation

if you wish to refer to users by a salutation (Ms, Dr, Hon, etc)

Demographics

Demographic data is also often used by customers to create segments and target specific groups of users.

Key
Definition

region

user’s city or nearby metro region (optional: ISO 3166-2) 1

postcode

the postal code of the user (varies by country) 1

location

if you use something besides the above for user location 1

gender

user's stated gender

birthdate

user's date of birth (strongly recommended unix timestamp)

birth_year

user's year of birth (e.g. 1998). If you only have a user's age, you can convert a user's age to birthyear 2

age_range

age range of a user (e.g. 18-35). If you do not have birthdate or birthyear but have demographic range 2

1 OneSignal already collects the user's country, so no need to send this as a tag.
2 OneSignal should not be initialized if the user is under the age of 13.

Activity

Using tags to track certain user activity is a popular way for customers to create segments.

Key
Definition

tutorial_status

if you have a tutorial to onboard users into your app, this is how far the user has gone (e.g. not started, step1, step5, completed)

Game-Specific

Customers with games apps often target messages to users based on their activity in the game. We recommend storing these as numeric where possible, in order to use greater than and less than operators.

Key
Definition

points

the amount of points / experience points a user has

level

the current level the user is on

highscore

the top score the user has achieved

Important Details & Guidelines

Data Formatting

  • Key names are case sensitive, and will not accept NULL.
  • Data values can contain up to 300 characters.
  • Data values must be JSON strings, numbers, or booleans (true or false). We do not accept object, nested hashes, or array data formats.

Data Formatting Best Practices

Numbers are more powerful - both text (strings) and numbers are supported as tag values, however when filtering users, strings can only check exact matches (is or is not). Meanwhile, numeric values also support less than and greater than operations, which can be useful for more fine-grained user targeting.

Avoid sending multiple, related booleans - we frequently see customers sending multiple boolean tags related to the same user attribute, where a better design would be to send a single tag. A single tag makes it easier to build segments, and keeps records cleaner. For instance:

Recommended
Not Recommended

user1

{user_type : "VIP"}

{isVIP : "TRUE", isPremium : "FALSE", isBasic : "FALSE"}

user2

{user_type : "Premium"}

{isVIP : "FALSE", isPremium : "TRUE", isBasic : "FALSE"}

user3

{user_type : "Basic"}

{isVIP : "FALSE", isPremium : "FALSE", isBasic : "TRUE"}

An easy rule of thumb is don't use booleans in any situation where a user may only have one possible value (VIP OR Premium OR Basic, but never two or three at the same time). While this is not possible for all types of data customers wish to store, it's easier to work with a smaller number of keys in the dashboard.

Stick to lowercase keys - unless you have a good reason otherwise, we recommend using all lowercase tag keys to ease confusion with whomever may be using tags in the dashboard.

Avoid extended characters - we do not recommend sending extended characters like ~!@#$%^&*'{}|\'" as these may not be interpreted correctly in your code.

What Data to Send

OneSignal automatically collects some data from devices, meaning you do not need to send certain data such as device type, country, push subscription status, etc. Data such as these are already captured by the OneSignal SDK, and may have more advanced filter logic available to them when creating Segments. See all data types collected in Data Collected by the OneSignal SDK.

What Data NOT to Send

Tags are meant to be used to filter and build segments of users, and are not meant as a store of user events. If you wish to store events, we recommend using a dedicated events database.

While there is no limit on the number of custom tags you can create, we recommend not assigning more than 20 tags per user if you have more than 3 million subscribers, otherwise notifications targeted by tag may impact delivery speeds.

Confirm Tags Are Working

If you've set up tags correctly, you'll see the user with the tagged value on the All Users page:

Notifications may be sent using tags both through the OneSignal Dashboard and programmatically using our REST API. To send notifications programmatically via the API, use Create Notification, which lets you send notifications targeting users matching certain tags using the filters parameter.


What's Next

Now that you've implemented tags, you can start using them to target users and personalize messages in Data & Tags. Or, return to setting up more features

Data & Tags
Features Setup

Add Data Tags


How to add user data tags to your OneSignal implementation for Web Push and Mobile.

Suggested Edits are limited on API Reference Pages

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