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

Add Data Tags

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

For Developers

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

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:

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.

Key
Definition

realname

user’s full real name

firstname

user’s first name

lastname

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: ISO 8061 YYYY-MM-DD format, e.g. 1998-10-14). Recommended age format. 2

birthyear

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

Try not to send values as keys - some customers use tags as boolean checks, e.g. {isVIP : "TRUE"} to check whether a user meet certain conditions. We recommend against this, and instead sticking to using keys to denote a data category, e.g. {user_type : "VIP"}, since you can check for more than one value. An easy rule of thumb is any situation where users may only have one possible value, don't store that value as a key. 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.

Only send simple strings or numbers - tags do not support arrays at this time, and will throw an error if you send them.

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.

Numbers are more powerful - both text (strings) and numbers are supported as tag values, however strings are limited to just checking for exact matches. Meanwhile, numeric values also support less than and greater than operations, which can be useful for more fine-grained user targeting.

OneSignal already gets some data from devices - sometimes customers will send tags with redundant data about users, such as device type, country, push subscription status, or last session time. 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.

Be mindful about adding unnecessary tags - there is no limit on the number of custom tags you can create, however 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. Tags aren't meant to be a store of user events.

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.

For Developers