Tags
Add custom properties and events to users.
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.
How add update and remove data tags
There are several ways to add, update, and remove tags as detailed below. Check out your plan details, for the number of custom data tags per user your plan is entitled to set.
- Data Tag SDK Methods: (Recommended) Quickly add, remove, or update tags in almost real-time when users perform actions or events on your site or mobile app. See our Mobile SDK Reference and Web SDK Reference.
- Create user or Update user: Server REST API endpoint for directly updating the
tags
parameter on single users. - Journeys: Set tags automatically within a Journey workflow as a user moves through a journey.
- Importing User Attributes or Data Tags: Upload a CSV of user data through the OneSignal Dashboard with the
subscription_id
orexternal_id
. This enables you to migrate existing data sources into OneSignal. - Web Category Prompt: If you are integrating OneSignal into your website, then you can add data tags by using our category slide-down prompt. This enables you to capture user interest around what type of messages they'd be interested in.
- User Profile Page: Quickly add and update data tags from the User Profile page UI in the OneSignal dashboard.
- In-App Messages: When you send in-app messages, you can collect data tags based on user engagement through clicks and our click actions. Additionally, data tags can also be used to trigger an in-app.
- Integrations: Depending on the integration partner, there are specific tags that can be set.
- Hubspot has a "Edit Tags" workflow option to set your own tags.
- Segment Integration syncs data passed within their SDK as tags.
- Mixpanel syncs
$first_name
and$last_name
properties as data tagsfirst_name
andlast_name
.
Importing Data Tags
Data tags can be added and updated for your users by utilising our CSV importer, our Update User API endpoint, or by manually updating them in the subscription details screen of the dashboard. See our Import User Tags guide for more details.
Export Users Over Tag Limit
Navigate to Audience > Subscriptions > Arrow next to Export.
This is the ability to export all subscriptions with N tags. Note. N will change depending on your plan type and is the plan-specific data tag limit. This ensures you can always remove tags for subscriptions above your current plan entitlement.
Export from Dashboard
Once you have selected Export you'll shortly receive an email to your account email address, to begin the download. We provide this via email, as you may export thousands or even millions of subscriptions.
The CSV will have two formats depending on whether you are exporting all subscriptions or the subscriptions with data tags above the plan allowance:
- Exporting All Users: This will include all metadata and columns shown in your dashboard. Data Tags export as a JSON blob.
- Exporting Users with 10 Tags: This provides a limited number of columns including both
subscription_id
andexternal_id
(if applicable), along with data tags, where each data tag key is a column, and each row represents a value that corresponds to thatid
.
Editing and Deleting Your Data Tags
The subscription data comes in a CSV format, which enables you to open in Excel, Google Sheets, or Apple's Numbers. Upon opening, you should now be able to effectively edit, or delete any tags as needed.
To delete a tag, include the tag name to be deleted as a column header, but leave an empty cell for the corresponding value. Under Advance Settings ensure that you click the checkbox for "Delete existing data tag values when the uploaded value is null" when importing your CSV to remove tags with null values for your users.
When saving the altered CSV, make sure that you save it as a CSV. Some editors will save it in their default format, for example, *.xslx
. Our importer does not accept any formats other than CSV.
Uploading your data tags
Now your data tags have been edited and deleted, you can now upload your subscribers back into OneSignal. See our Data Tag Import guide for details on how to upload your new file.
FAQ
What if I don't have the external_id set?
OneSignal intentionally does not automatically collect Personally Identifiable Information for data privacy reasons. If you have not enriched OneSignal with the external_id
property or Data Tags, it can be difficult to map the user record in OneSignal with your database user record. Based on Data Collected by the OneSignal SDK like IP Address and Device (along with any data tags you may have set), you could try Exporting User Data from OneSignal and match any data within your database to map users to a CSV and upload using the onesignal_id
and adding the external_id
and other tag columns.
For proper user matching, we highly recommend adding the external_id
through our client-side SDK. See Users for more details.
How many tags can I set?
Check your plan limits, for the number of custom data tags per user. If you need more, contact our sales team to discuss more options.
Where can I check how many tags my users have?
Navigate to Audience > Users page "Tags" column or see Exporting User Data.
How do I know if I’m using more tags than my current plan allows?
You can export the specific users over the plan limit within the dashboard Audience > Users > Export. Details in Bulk Updating User Attributes or Data Tags.
How do I reduce the number of data tags my app is using?
There are several options including API updates to uploading a CSV. See Tags: Tracking User Events and Attributes for a list of all options.
What happens to my data tags if am over the plan entitlement?
Your application will continue to have the data tags set per user. When adding or updating tags, you won't be able to make changes to users over your plan limits. This means if a user is at or over their tag limit, you will first need to delete the unwanted tags, then make another request to add or update the desired tags.
For example, if your account tag limit is 20 custom tags per user, then each user can only have 20 unique tag "keys" set at once.
If a user has 0 tags:
- Any request to set 1-20 tag keys, will succeed.
- Any request to set 21+ tag keys, will fail, no tags will be set.
If a user has 19 tags:
- A request to set 1 new tag key will succeed.
- A request to set 2+ new tag keys will fail, no new tags will be set.
- A request to update 1-19 of the currently set tag values and set 1 new tag will succeed.
- A request to update 1-19 of the currently set tag values and set 2+ new tag will fail. You need to make 2 requests. 1st to delete the unwanted tag keys, 2nd to set the new tag keys.
Why are data tags not showing on my device?
There are a few reasons why tags may not be set listed below.
Offline or Unstable Network Connection
The most common reason for tags not showing on a device is due to unstable or no network connection where the request to update the tags does not make it to OneSignal.
Android Mobile SDKs will cache data tags and will retry adding the tag upon detecting a stable internet connection.
iOS Mobile SDKs provides a callback for you to handle this case.
Web SDK, the user must be subscribed before the tag is added to the device record. Once the user registers, the tags will automatically be sent to our server as long as the page session is the same (the user has not navigated to another page).
End of Page Session
Web SDK - If the person leaves the page before the tags are set, they will not get the tags.
Clearing Browser Cache
When web subscribers clear their browser data/cookies/cache it destroys the push records for al sites that the user is subscribed under. OneSignal provides a feature to automatically resubscribe the user upon returning to the site with our SDK, but this will not add the tags back unless some additional steps are taken. See What happens when I clear browser cookies? for more details.
Best Practices
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 support 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.
User 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".
Key | Definition |
---|---|
cart_update or last_reload | Most 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_paid | Most recent date the user finished a purchase or order. Set value as a Unix Timestamp in seconds to use Time Operators. |
amount_spent | Track how much money the user spent. Recommended to use integers 100 , 35 . Don't use $ or currency. |
social_share or referrals | When 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_click | Most recent date the user clicked a notification. Value set as a Unix Timestamp in Seconds. See our Auto-Segment By Notification Data. |
tutorial_status | If 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.
Key | Definition |
---|---|
points | The amount of points/experience points a user has |
level | The current level the user is on |
high_score | The 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.
Key | Definition |
---|---|
user_type | Type or tier of account users have (for example, free , premium , VIP , admin ) |
has_downgraded | If 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_privileges | Track 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 or add a custom alias.
Key | Definition |
---|---|
first_name | User’s first name |
last_name | User’s last name |
user_name | Name 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.
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 | Alternative to region and postcode for storing a custom location1 |
birthdate | User's date of birth (strongly recommended to be a Unix timestamp) |
birth_year | User's year of birth (example: 1998 )2 |
age_range | Age range of a user (example: 18-35 )2 |
1 OneSignal SDK collects the user's country.
2 OneSignal should not be initialized if the user is under the age of 13.
Updated 6 days ago