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.