Data Tags

How to add custom data attributes to your OneSignal Users.

📘

You're Viewing User Model Documentation 🎉

OneSignal is in the process of migrating from a device-centric model (player ID) to a new user-centric data model (OneSignal ID). To learn more, check out the User Model Migration Guide.

Please refer to Version 9 of our documentation for device-centric information.

Tags are custom key : value pairs of String data that are unique to each user or subscription. They can be used for tracking user events and properties. Use tags to track events like "adding an item to the cart" or user properties like "first_name" or "VIP status". Tags are stored for the lifetime of the user record until removed or deleted. Tags are essential for targeting audiences, personalizing messages, and evaluating user behaviors.


Recommended Tags

Use simple key: value pairs of String data for optimized performance. Integers and decimals sent as Strings can be used as numbers for segmentation with "greater than" and "less than" operators. Also, unix timestamps in seconds can be used for Time Operators. We do not recommend using Arrays, Objects, or Lists as tag values.

🚧

Do Not Set User IDs

Do not use tags for setting "user IDs" or sending messages to individual users. Instead use the External ID and alias properties.

Use lowercase keys - Unless you have a good reason otherwise (like saving the user's name), we recommend using all lowercase tag keys to reduce confusion for whoever may be using tags in the OneSignal Dashboard.

Avoid extended characters - We do not recommend sending extended characters, like ~!@#$%^&*'{}|\'", as these may not be interpreted correctly in your code. Spaces, periods (or "dots"), etc in tag keys cannot be substituted/processed and will result in a blank. Only use alphanumeric characters and an underscore ("_") or hyphen ("-") in your tag keys if needed.

Numbers are Powerful - Both text and numbers set as String data types are supported as tag values. Text data can be filtered with exact matches ("is" or "is not") while numeric values also support "less than" and "greater than" operations, which can be useful for more fine-grained user targeting.

Timestamps - Use unix timestamps in seconds to measure how long it has been since a user performed an action. See Time Operators for details.

Other Best Practices:

  • Do not set Arrays, Objects, or Lists as tag values.
  • Keep tags as short as possible. The fewer characters, the better. For example, use "1" or "t" instead of "true".
  • Instead of using "true" or "false", count things! Set the value to be a number or Unix timestamp in seconds to count things or track time since.
  • Use tags that are valuable for event-triggered messages, like Abandoned Cart notifications.

Activity

Event-driven data based on user actions. "keys" should identify the action while "values" should be integers representing "how many times the action was performed" or Unix Timestamps for "when/how long it has been since the action was taken".

KeyDefinition
cart_update or last_reloadMost recent date the user added an item to their shopping cart or expressed interest in a purchase (usually through clicking a button).

Recommended tag value as a Unix Timestamp in seconds to use Time Operators.

See our Abandoned Cart guide.
last_order or last_paidMost recent date the user finished a purchase or order. Set value as a Unix Timestamp in seconds to use Time Operators.
amount_spentTrack how much money the user spent. Recommended to use integers 100, 35. Don't use $ or currency.
social_share or referralsWhen a user clicks a social share button or refers a friend, tag them with how many times they did it. Later reward the user or ask for an App Rating. Example: 0, 1
last_notification_clickMost recent date the user clicked a notification. Value set as a Unix Timestamp in Seconds. See our Auto-Segment By Notification Data.
tutorial_statusIf you have a tutorial to onboard users into your app, this is how far the user has gone. Example: 0 or not_started, 1 or step1, 5 or step5, completed

Game-Specific

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

KeyDefinition
pointsThe amount of points/experience points a user has
levelThe current level the user is on
highscoreThe top score the user has achieved

Account-Related Data

Adding account-related tags is 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.

Do not use tags for setting "user IDs" or sending messages to individual users. Instead use the External ID property.

KeyDefinition
user_typeType or tier of account users have (for example, free, premium, VIP, admin)
has_downgradedIf the user was a paid or higher tier user that downgraded, tag them with true or 1 or a value as Unix Timestamp in seconds to track how long ago they downgraded.
user_privilegesTrack user privileges in addition to type (for example, administrator, early access, normal, guest)

For instance, when tracking upgrade or downgrade events (after purchase or cancelation), you can update these tags to target free vs premium users with different messages.

These events are perfect for matching with Time Operators to track when the upgrade or downgrade event occurred. If you provide subscription plans, you can set up "reminder messages" to let the customer know their plan is about to expire.

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 and then use Variable Substitution when crafting your messages.

Do not use tags for setting "user IDs" or sending messages to individual users. Instead use the External ID property.

KeyDefinition
first_nameUser’s first name
last_nameUser’s last name
user_nameName that users give themselves; often not a real name (example: PokeCatcher22)

Location & Demographics

Demographic data can be used to create segments and target specific groups of users.

KeyDefinition
regionUser’s city or nearby metro region (optional: ISO 3166-2) 1
postcodeThe postal code of the user (varies by country)1
locationAlternative to region and postcode for storing a custom location1
birthdateUser's date of birth (strongly recommended to be a Unix timestamp)
birth_yearUser's year of birth (example: 1998)2
age_rangeAge range of a user (example: 18-35)2

1 OneSignal collects the user's country.
2 OneSignal should not be initialized if the user is under the age of 13.