Data Tags SDK Methods
Available options to add Data Tags to devices with OneSignal.
Data Tags
OneSignal tags are custom key : value
pairs of string data for setting custom user or event properties. This guide details how to add tags through the SDK, but tags can also be added through:
- Server-side APIs: Edit device & Edit tags with external user id.
- List Upload: Importing User Attributes or Tags.
Tags should be added as string
data, but any numbers/integers/decimals will be detected automatically on our backend and available for use.
Not for User IDs
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.
Tag a user based on an event of your choosing so later you can create Segments or Message Personalization. Recommend using addTags
over addTag
if you need to set more than one tag on a user at a time.
Adding a tag
Add a tag for the current user. If the tag key already exists, it will be replaced with the value provided here. If you try to set more tags on a user than you plan allows, it will fail. You will need to delete any unwanted tags first before setting or updating tags. See Tags FAQ for details.
OneSignal.getUser().addTag("KEY", "VALUE");
OneSignal.User.addTag("KEY", "VALUE")
OneSignal.User.addTag(key: "KEY", value: "VALUE")
[OneSignal.User addTag:@"KEY" value:@"VALUE"];
OneSignal.User.addTag("KEY", "VALUE");
OneSignal.User.AddTag("KEY", "VALUE");
OneSignal.User.addTag('my_tag', 'tag');
OneSignal.User.addTagWithKey("test1", "val1");
window.plugins.OneSignal.User.addTag("KEY", "VALUE");
Adding multiple tags at once
Add multiple tags for the current user. A tag key will be replaced with its corresponding value if it already exists. If you try to set more tags on a user than you plan allows, it will fail. You will need to delete any unwanted tags first before setting or updating tags. See Tags FAQ for details.
OneSignal.getUser().addTags(new HashMap<String, String>() {{
put("KEY_01", "VALUE_01");
put("KEY_02", "VALUE_02");
}});
OneSignal.User.addTags(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))
[OneSignal.User addTags:@{@""KEY_01"": @""VALUE_01"", @""KEY_02"": @""VALUE_02""}];
OneSignal.User.addTags(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"])
const tags = {
KEY_01: "VALUE_01",
KEY_02: "VALUE_02",
KEY_03: "VALUE_03"
};
OneSignal.User.addTags(tags);
OneSignal.User.AddTags(new Dictionary<string, string> {
{ "KEY_01", "VALUE_01" },
{ "KEY_02", "VALUE_02" }
});
OneSignal.User.addTags({my_tag1: 'my_value', my_tag2: 'my_value2'});
var tags = {'test': 'value', 'test2': 'value2'};
OneSignal.User.addTags(tags);
window.plugins.OneSignal.User.addTags({"KEY_01": "VALUE_01", "KEY_02": "VALUE_02"});
Removing a tag
Remove the data tag with the provided key from the current user.
OneSignal.getUser().removeTag("KEY");
OneSignal.User.removeTag("KEY")
[OneSignal.User removeTag:@"KEY"];
OneSignal.User.removeTag("KEY")
OneSignal.User.removeTag("KEY");
OneSignal.User.RemoveTag("KEY");
OneSignal.User.removeTag('my_tag1');
OneSignal.User.removeTag("test");
window.plugins.OneSignal.User.removeTag("KEY");
Removing multiple tags at on
Remove multiple tags from the current user.
OneSignal.getUser().removeTags(Arrays.asList("KEY_01", "KEY_02"));
OneSignal.User.removeTags(listOf("KEY_01", "KEY_02"))
[OneSignal.User removeTags:@[@""KEY_01"", @""KEY_02""]]
OneSignal.User.removeTags([""KEY_01"", ""KEY_02""])
const tags = ['KEY_01', 'KEY_02', 'KEY_03'];
OneSignal.User.removeTags(tags);
OneSignal.User.RemoveTags(new string[] { "KEY_01", "KEY_02" });
OneSignal.User.removeTags(['my_tag1', 'my_tag2']);
OneSignal.User.removeTags(["test", "test2"])
window.plugins.OneSignal.User.removeTags(["KEY_01", "KEY_02"]);
Getting tags
Requires SDK 5.0.5+
Gets the local tags for the current user. Remote tags are pulled and stored locally when the user changes after calling the login
method or on a new session. A new session starts when your app is opened after 30 seconds of being out-of-focus.
Map<String, String> tags = OneSignal.getUser().getTags();
val tags: Map<String, String> = OneSignal.User.getTags()
let tags = OneSignal.User.getTags()
NSDictionary<NSString*, NSString*> *tags = [OneSignal.User getTags]
const tags = OneSignal.User.getTags()
const getTags = async () => {
const tags = await OneSignal.User.getTags();
loggingFunction('Tags:', tags);
};
Examples
Tagging based on browser or OS
If you want to segment by mobile web vs. desktop web subscribers, you can use this example code on your site to tag automatically once detected
// Example from Stackoverflow https://stackoverflow.com/questions/1005153/auto-detect-mobile-browser-via-user-agent
OneSignalDeferred.push(function(OneSignal) {
if (navigator.appVersion.indexOf("Mobile") !== -1)
OneSignal.User.addTag("device_type", "mobile")
else
OneSignal.User.addTag("device_type", "desktop")
})
Tag by OS and browser
We track by device type
, which you can use to create Segments to independently target Android and iOS mobile app subscribers and Web Push subscribers.
// Example from Stackoverflow: https://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript
const os =
navigator.userAgent.indexOf("Mac") !== -1
? "Macintosh"
: navigator.userAgent.indexOf("Linux") !== -1
? "Linux"
: navigator.userAgent.indexOf("Android") !== -1
? "Android"
: navigator.userAgent.indexOf("like Mac") !== -1
? "iOS"
: "Unknown OS"
console.log('Your OS: ' + os);
const browser =
navigator.userAgent.indexOf("Safari") !== -1
? "Safari"
: navigator.userAgent.indexOf("Chrome") !== -1
? "Chrome"
: navigator.userAgent.indexOf("OPR") !== -1
? "Opera"
: navigator.userAgent.indexOf("Firefox") !== -1
? "Firefox"
: "Unknown Browser"
console.log('Your browser: ' + browser);
OneSignalDeferred.push(function(OneSignal) {
OneSignal.User.addTags({
os,
browser,
})
});
Additional Guides
See Data Tags for ideas on what tags to use and Tags: Tracking User Events and Attributes for more ways to set tags. Other examples:
- Example: Abandoned Cart - remind users to make those purchases!
- Example: Tag with Notification Data - tag users based on types of notifications they click.
- Example: Tag with Subscription Page - tag users based on the page they subscribed on.
- Example: Tag Page Visits - tag users based on how many times they visit certain topics of your app or site.
Troubleshooting
See Data Tags FAQ for details.
Updated 2 days ago