Data Tags

How to add custom data attributes to your OneSignal Users.

Data tags are custom key : value pairs of string data used to add custom properties or event data to user records within OneSignal. Tags are stored for the lifetime of the record until removed or deleted using the options listed below. Tags are essential for targeting audiences, personalizing messages, and evaluating user behavior.

Tags are the building blocks for:

🚧

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.

Depending on your OneSignal account type, you may be limited on the amount of tags you can set per device record. See our pricing page for details on tag limits.


Adding / Editing Data Tags

Once you've integrated OneSignal in your app or website, you can implement tags in the following ways:

OptionDetails
SDK Methods
- sendTag
- sendTags
Recommended: Quickly add, remove, or update tags in almost real time when users perform actions or events on your site or mobile app.
API Edit device

API Edit tags with external user id
Server REST API endpoint for directly updating the tags parameter on single devices with player_id or external_user_id.
User Profile pageQuickly add and update tags from the User Profile page UI in the OneSignal dashboard.
CSV List UploadUpload a CSV of user data through the OneSignal Dashboard with the player_id or external_user_id.
Web Category PromptTags can be added/removed through a drop down prompt from your website.
In-App MessagesTags can be added with click actions when clicking button or image blocks.
JourneysTag users automatically within a Journey workflow.
Integrations- Hubspot has a "Edit Tags" workflow option.
- Segment Integration syncs tags.
- Mixpanel syncs first_name and last_name properties as tags.

Tag limits apply based on your Account Type. It's recommended to tag devices with simple and short key : value data used for messaging purposes.


Recommended Tags to Send

The OneSignal SDK collects some data automatically. You do not need to tag data such as device type, country, push subscription status, or language. It is recommended to consider what data is required for targeting your users.

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

Example: OneSignal.sendTag("times_event_performed", "3"); or OneSignal.sendTag("when_event_performed", "1605847987");

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

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

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 a purchase or cancelation), you can update these tags for targeting free vs premium users with different messages.

//Upgrade event or user login and "paid user" detetected
OneSignal.sendTag("user_type", "premium");

//Upon a downgrade event, we can mark the user to send promotions or surveys to ask why they downgraded
OneSignal.sendTag("user_type", "free_downgraded");

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.

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.


Data Formatting Best Practices

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

Tags are not meant to be arrays or lists. You should use simple key : value pairs of string data for optimized performance. Integers, Floats, Doubles, decimals sent as strings can be used as numbers for Segments.

  • Key names are case sensitive, and will not accept NULL.
  • Data values can contain up to 300 characters.
  • Data values should be sent as JSON strings.

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:

RecommendedNot 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 (for example, 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.

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 ("_").

FAQ

How can I find and confirm tags are applied?

If you've setup tags correctly, you'll see the user with the tagged value in the OneSignal Dashboard on the All Users page:

13821382

Can I tag users through the Server API?

You can add, update, and remove tag data with the Edit Device API call and OneSignal player_id or Edit tags with external user id and external_user_id.

Android Cache Warning: data synchronization issues may occur if you try updating the same tag set with SDK and API.

The OneSignal Android SDK caches tag data to automatically retry sending if device is offline or fails to send data to OneSignal.

If you set a tag with the SDK (tag: 1) and then change it with the API (tag: 2), the Android SDK "thinks" the tag is still set to the original value (tag: 1) and will not attempt to update it back if the method is called again using the original value.

In this case, you can set the tag through the SDK to be a different tag value (tag: 3) and then it will update, or you can separate tags set by the API and SDK to make sure that they do not overlap.


What’s Next