OneSignal tags are custom key : value pairs of string or integer data that can be added to devices through our SDK, API, or List Upload. Tags unlock three important features:

• Targeting specific or groups of users with messages using Segments or the API tag Filter.
• Personalizing messages to users with Tag Substitution.
• Integrating with your Internal Database & CRM for analytics and tracking.

More Tagging Examples at the bottom of this guide including samples from the video.

Implementation

The OneSignal SDK collects some data automatically, so you do not need to tag data such as device type, country, push subscription status, or language.

Once you've integrated OneSignal in your app or website, you can implement tags through several methods:

• SDK sendTag & sendTags 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 below Tagging Examples.
• AP Edit device - Server REST API endpoint for directly updating the tags parameter on a single device with player_id.
• API Edit tags with external user id - Server REST API endpoint to update the tags on one or more devices based on the external_user_id sent to OneSignal.
• List Upload Feature - Upload a CSV of user data through the OneSignal Dashboard with the player_id or external_user_id.

Recommended Tags to Send

Tags are not meant to be arrays or lists. You should use simple key : value pairs of string or integer data for optimized performance. OneSignal is not meant to be a database. If you wish to store thousands of attributes, we recommend using a dedicated Database, DMP, or CRM.

Common best practices:

• Keep tags as short as possible. The fewer characters the better. For example, use 1 for true.
• OneSignal allows "greater than", "less than" and Time Elapsed operators to be used with tags having integer values. Instead of using true and/or false, 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.

Note: Data is not automatically tagged. Your app/site must already collect information in order to send it as tags.

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.

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.

These data tags are available for use in Email Messaging, so we recommend using these exact key names.

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.

Activity

You can use tags to track certain user activity to create segments and target users who have performed the activity.

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.

Data Formatting Best Practices

• 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). OneSignal does not accept objects, nested hashes, or array data formats.

Numbers are 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. Also, you can use Unix Timestamps in Seconds for Time Operators which measure how long it has been since a user performed an action.

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:

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.

Confirming Tags Are Applied

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

Frequently Asked Data Tag Questions

Can I tag users through the API?

You can add, update, and remove tag data with the Edit Device API call and OneSignal Player ID. You can also add, update, and remove tag data on one or more devices based on an External User Id using the Edit Tags API (This option requires a OneSignal paid account).

Android: Updating the same tags from both the API and SDK on Android is not recommended, due to a data synchronization optimization.

For example:

If you set a tag on a device with the SDK (tag: 1), and then change it with the API to tag: 2, and then try to change it back to the original value set with the SDK (tag: 1), it will not update, since the SDK believes that the value is already the original value. In this case, you can set the tag through the SDK to be tag: 3 and it will update, or you can separate tags set by the API and SDK to make sure that they do not overlap.

This is currently only the case for Android, but may be implemented in the OneSignal iOS and Web SDKs at a later date.

Why are tags not working?

Device is Offline

When you use OneSignal tagging methods through the SDK, if the device does not have a network connection, then the tag will not get updated right away.

Our iOS Mobile SDK provides a callback for you to handle this case.

For Web, 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). Our Android Mobile SDKs have a feature which automatically handle offline support, and will retry adding the tag upon detecting a stable internet connection.

Free Plan with 10 Tags

If you encounter a "10 tags" error, it means that the user's device has reached 10 tags, and you need to either delete some tags, or upgrade to a paid OneSignal plan in order to add more.

It's important to note that on Android devices using any of our mobile SDKs, the tags can be cached, and they will need to be deleted in order to add more.

You can check for tags with our getTags() method and delete the tags you don't need with our deleteTags() method.

Troubleshooting

If you are still having issues, please plug the device into your IDE and use our SetLogLevel method to Verbose. Then attempt to reproduce the issue you are seeing. This will help log any issues to your IDE console.

If you need further help, please contact OneSignal Support and be prepared to provide us with these logs through Pastebin or a .txt file.

Tagging Examples

Tag Based on Browser or Operating System

OneSignal currently tracks device type, which you can use to create Segments to target Android and iOS mobile app subscribers and Web Push subscribers independently.

If you want to segment by mobile web vs. desktop web subscribers, you can use this example code on the site to tag automatically once detected:

// Example from Stackoverflow https://stackoverflow.com/questions/1005153/auto-detect-mobile-browser-via-user-agent
OneSignal.push(function() {
  if (navigator.appVersion.indexOf("Mobile") > -1) {
    OneSignal.sendTag("device_type","mobile");
  } else {
    OneSignal.sendTag("device_type","desktop");
  }
});

For segmenting around all different types of Operating Systems and Browsers, you can use this more in-depth tagging options:

// Example from Stackoverflow: https://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript
var os = "Unknown OS";
if (navigator.userAgent.indexOf("Win") != -1) os = "Windows";
if (navigator.userAgent.indexOf("Mac") != -1) os = "Macintosh";
if (navigator.userAgent.indexOf("Linux") != -1) os = "Linux";
if (navigator.userAgent.indexOf("Android") != -1) os = "Android";
if (navigator.userAgent.indexOf("like Mac") != -1) os = "iOS";
console.log('Your os: ' + os);

var browserType = "Unknown Browser Type";
if (navigator.userAgent.indexOf("Safari") != -1) browserType = "Safari";
if (navigator.userAgent.indexOf("Chrome") != -1) browserType = "Chrome";
if (navigator.userAgent.indexOf("OPR") != -1) browserType = "Opera";
if (navigator.userAgent.indexOf("Firefox") != -1) browserType = "Firefox";
console.log('Your Browser: ' + browserType);

OneSignal.push(function() {
  OneSignal.sendTags({
    os: os,
    browserType: browserType,
  }).then(function(tagsSent) {
    // Callback called when tags have finished sending 
    console.log("tagsSent: ", tagsSent);
  });
});

Get and Delete All Tags

Example of fetching all tags and deleting them.

OneSignal.getTags({tagsReceived in
    print("tagsReceived: ", tagsReceived.debugDescription)
    var tagsArray = [String]()
    if let tagsHashableDictionary = tagsReceived {
      tagsHashableDictionary.forEach({
        if let asString = $0.key as? String {
          tagsArray += [asString]
        }
      })
    }
    print("tagsArray: ", tagsArray)
    OneSignal.deleteTags(tagsArray, onSuccess: { tagsDeleted in
        print("tags deleted success: ", tagsDeleted.debugDescription)
    }, onFailure: { error in
        print("deleting tags error: ", error.debugDescription)
    })
})

Additional Guides

See our Use Cases & Best Practices guide for more tag examples like:

• Auto-Segment By Subscription Page - tag users based on the page they subscribed on.
• Auto-Segment By Page Visit - tag users based on how many times they visit certain topics of your app or site.
• Auto-Segment By Notification Topic - tag users based on types of notifications they click.
• Abandoned Cart - remind users x amount of time after they added an item to the cart.