Overview
OneSignal supports tagging users with simple string data. Tags unlock three important features of OneSignal:
Targeting notifications to specific users or groups using Segments
Personalizing messages to users with
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:
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.
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.
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.
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.
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.
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:
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 |