Log InSign Up

Data Tags SDK Methods

Available options to add Data Tags to devices with OneSignal.

Suggest Edits

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:

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();
    console.log('Tags:', tags);
};

const getTags = async () => {
    const tags = await window.plugins.OneSignal.User.getTags();
    console.log('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:

Troubleshooting

See Data Tags FAQ for details.

Updated 4 months ago

What’s Next