Data tags are key : value pairs of data used to add custom events and properties to users. Use tags to track events like "adding an item to the cart" or user properties like they "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 behavior.

---

Recommended Tags

Use simple key: value pairs of String data for optimized performance. Integers, Floats, Doubles, and decimals sent as strings can be used as numbers for Segments. We recommend you not use Arrays, Objects, or Lists.

Use lowercase keys - Unless you have a good reason otherwise, we recommend using all lowercase tag keys to ease confusion for whomever may be using tags in the OneSignal Dashboard.

Avoid extended characters - We do not recommend sending extended characters, like [email protected]#$%^&*'{}|\'", 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.

🚧

Not for User IDs

Do not use tags for setting "user Ids" or sending messages to individual users. Instead use the External User Id property.

OneSignal is not meant to be a database. If you wish to store complex user attributes, we recommend using a dedicated Database, DMP, or CRM.

Numbers are Powerful - Both text and numbers 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.

Also, you can use Unix Timestamps in Seconds for Time Operators which measure how long it has been since a user performed an action.

• Keep tags as short as possible. The fewer characters the better. For example, use 1 for true.
• Instead of using true or false, count things! Set the value to be an integer like 1 or 1000 that you can increment the more a user does the action. Examples: Increment By Page Topic Visits or Increment By Notification Topic.
• Use tags that are valuable for event triggered messages, like Abandoned Cart notifications.
• Only use alphanumeric characters and an underscore ("_"). Spaces, Periods (or "dots"), etc in tag keys cannot be substituted/processed and will result in a blank.

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".

Game-Specific

Customers with games 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.

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.

Do not use tags for setting "user Ids" or sending messages to individual users. Instead use the External User Id property.

For instance, when tracking upgrade or downgrade events (after a purchase or cancelation), you can update these tags for targeting 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 setup "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 User Id property.

Location & Demographics

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

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