The methods below require the OneSignal SDK versions 3 & 4.It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.See Update to User Model for migration steps.

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 be set in a number of ways outlined in Tags: Tracking User Events and Attributes Tags should be added as string data, but any numbers/integers/decimals will be detected automatically on our backend and available for use.

Do not use tags for setting “user Ids” or sending messages to individual users. Instead use the External User Id property.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.

SDK Tagging Methods

Tag a user based on an event of your choosing so later you can create Segments or Message Personalization. Recommend using sendTags over sendTag if you need to set more than one tag on a user at a time. iOS SDK implements callbacks to verify tags were successfully added. Android saves tags to device cache and will retry updating the tag automatically upon a stable network connection being established.

`sendTag` Method

Tag a user based on an app event of your choosing so later you can later create segments to target these users. We recommend using sendTags over sendTag if you need to add or update more than one tag on a user at a time. 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 Data Tags for details.

Parameter	Type	Description
`key`	String, NSString*	Key of your choosing to create or update
`value`	String, NSString*	Value to set on the key. NOTE: Passing in a blank String deletes the key, you can also call `deleteTag` or `deleteTags`.
`onSuccess(Optional)`	OneSignalResultSuccessBlock	iOS Called if there were no errors sending the tag.
`onFailure(Optional)`	OneSignalFailureBlock	iOS Called if there was an error. Android Will retry automatically upon a stable network connection.
`callback` (Web)	Function	Call back to be fired when the tags have been sent to our server and a response has been returned. The first parameter of the callback is an object of the tags you sent (key-value pairs).

//Returns a Promise resolving with the object key-pairs of the tags you sent, 
//or rejected with an error.

//Example with callback
OneSignal.push(function() {
  OneSignal.sendTag("key", "value", function(tagsSent) {
    // Callback called when tags have finished sending
  });
});

// Another callback example
OneSignal.push(function() {            
  OneSignal.sendTag("key", "value").then(function(tagsSent) {
    // Callback called when tags have finished sending
  }); 
});

//Example without callback
OneSignal.push(function() {
  /* These examples are all valid */
  OneSignal.sendTag("key", "value"); 
});

OneSignal.sendTag("key", "value");

OneSignal.sendTag("key", value: "value")

[OneSignal sendTag:@"key" value:@"value"];

OneSignal.Default.SendTag("tagName", "tagValue");

OneSignal.sendTag("key", "value");

window.plugins.OneSignal.sendTag("key", "value");

//Example without callback
OneSignal.shared.sendTag("test", "value");

//Example with callback
OneSignal.shared.sendTag("key", "value").then((response) {
  print("Successfully sent tags with response: $response");
}).catchError((error) {
  print("Encountered an error sending tags: $error");
});

OneSignal.Current.SendTag("key", "value");

OneSignal.SendTag("CoronaTag1", "value1")

`sendTags` Method

Tag a user based on an app event of your choosing, so that later you can create segments to target these users. 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 Data Tags for details.

Parameter	Type	Description
`keyValues`	JSONObject, NSDictionary*	Key value pairs of your choosing to create or update. NOTE: Passing in a blank `NSString*` as a value deletes the key, you can also call `deleteTag` or `deleteTags`.
`onSuccess(Optional)`	OneSignalResultSuccessBlock	iOS Called if there were no errors sending the tag.
`onFailure(Optional)`	OneSignalFailureBlock	iOS Called if there was an error. Android Will retry automatically upon a stable network connection.
`callback` (Web)	Function	Call back to be fired when the tags have been sent to our server and a response has been returned. The first parameter of the callback is an object of the tags you sent (key-value pairs).

//Returns a Promise resolving with the object key-pairs of the tags you sent, 
//or rejected with an error.

//Example with callback
OneSignal.push(function() {
  OneSignal.sendTags({
    key: 'value',
    key2: 'value2',
  }, function(tagsSent) {
    // Callback called when tags have finished sending    
  });
});

//Another example with callback
OneSignal.push(function() {
  OneSignal.sendTags({
    key: 'value',
    key2: 'value2',
  }).then(function(tagsSent) {
    // Callback called when tags have finished sending    
  });
});

//Example without callback
OneSignal.push(function() {
  OneSignal.sendTags({key: 'value'});
});

//Another example without callback
OneSignal.push(function() {
  OneSignal.sendTags({
    key: 'value',
    key2: 'value2',
  });
});

JSONObject tags = new JSONObject();
tags.put("key1", "value1");
tags.put("key2", "value2");
OneSignal.sendTags(tags);

OneSignal.sendTags(["key1": "value1", "key2": "value2"])

[OneSignal sendTags:@{@"key1" : @"value1", @"key2" : @"value2"}];

OneSignal.Default.SendTags(new Dictionary<string, object> { 
    { "tag1", "123" },
    { "tag2", "abc" }
});

OneSignal.sendTags({key: "value", key2: "value2"});

window.plugins.OneSignal.sendTags({key: "value", key2: "value2"});

//Example without callback
OneSignal.shared.sendTags({"test_key_1" : "test_value_1", "test_key_2" : "test_value_2"});

//Example with callback
OneSignal.shared.sendTags({"test_key_1" : "test_value_1", "test_key_2" : "test_value_2"})
.then((response) {
  print("Successfully sent tags with response: $response");
}).catchError((error) {
  print("Encountered an error sending tags: $error");
});

OneSignal.Current.SendTags(new Dictionary<string, string>() { {"TestKey2", "value2"}, {"TestKey3", "value3"} });

OneSignal.SendTags({["CoronaTag2"] = "value2",["CoronaTag3"] = "value3"})

`getTags` Method

Retrieve a list of tags as that have been set on the user from the OneSignal server. Android will provide a cached copy if there is no network connection.

//Returns a Promise resolving with the object key-pairs of the tags you sent
//or rejected with an error.

//All examples are valid.

OneSignal.push(function() {
  OneSignal.getTags(function(tags) {
    // All the tags stored on the current webpage visitor
  });
});

OneSignal.push(function() {
  OneSignal.getTags().then(function(tags) {
    // All the tags stored on the current webpage visitor
  });
});

OneSignal.push(["getTags", function(tags) {
	console.log("OneSignal getTags:");
  console.log(tags);
}]);

//The tagsAvailable callback does not return on the Main(UI) Thread, so be aware when modifying UI in this method.
OneSignal.getTags(new OSGetTagsHandler() {
	@Override
	public void tagsAvailable(JSONObject tags) {
    //tags can be null
    if (tags !== null) {
      Log.d("debug", tags.toString());
    }
  }
});

OneSignal.getTags({ tags in
	print("tags - \(tags!)")
}, onFailure: { error in
	print("Error getting tags - \(error?.localizedDescription)")
})

[oneSignal getTags:^(NSDictionary* tags) {
	NSLog(@"%@", tags);
}];

var tags = await OneSignal.Default.GetTags();
var tag3Value = tags["tag3"];

OneSignal.getTags((receivedTags) => {
    console.log(receivedTags);
})

window.plugins.OneSignal.getTags(function(tags) {
  console.log('Tags Received: ' + JSON.stringify(tags));
});

Map<String, dynamic> tags = await OneSignal.shared.getTags();

void SomeMethod() {
		OneSignal.GetTags(TagsReceived);
	}

	private void TagsReceived(Dictionary<string, object> tags) {
		foreach (var tag in tags)
			print(tag.Key + ":" + tag.Value);
	}

function printAllTags(tags)
   for key,value in pairs(tags) do
      print( key, value )
   end
end

OneSignal.GetTags(printAllTags)

Parameter	Type	Description
`tags`	JSON Object of `String` data	Contains key-value pairs retrieved from the OneSignal server.
`successBlock`	OneSignalResultSuccessBlock	Called when tags are received from OneSignal’s server.
`onFailure(Optional)`	OneSignalFailureBlock	Called if there was an error.
`tagsReceivedCallBack` (Web)	Function (Web)	Callback to be fired when the list of tags has been retrieved. The first parameter of the callback is an object containing key-value pairs of the tags.

`deleteTag` Method

Deletes a single tag that was previously set on a user with sendTag or sendTags. Use deleteTags if you need to delete more than one.

Parameter	Type	Description
`key`	String, NSString*	Key to remove
`onSuccess(Optional)`	OneSignalResultSuccessBlock	iOS Called if there were no errors
`onFailure(Optional)`	OneSignalFailureBlock	iOS Called if there was an error Android Will retry automatically upon a stable network connection.

//Returns a Promise resolving with the object key-pair of the tag you deleted, 
//or rejected with an error.
OneSignal.push(function() {
  OneSignal.deleteTag("tagKey");
});

OneSignal.deleteTag("key");

OneSignal.deleteTag("key")

[OneSignal deleteTag:@"key"];

OneSignal.Default.DeleteTag("tag4");

OneSignal.deleteTag("key");

window.plugins.OneSignal.deleteTag("key");

await OneSignal.shared.deleteTag("test");

OneSignal.DeleteTag("key");

OneSignal.DeleteTag("CoronaTag1")

`deleteTags` Method

Deletes one or more tags that were previously set on a user with sendTag or sendTags.

Parameter	Type	Description
`keys`	Array, Collection, NSArray*	Keys to remove.
`onSuccess(Optional)`	OneSignalResultSuccessBlock	iOS Called if there were no errors
`onFailure(Optional)`	OneSignalFailureBlock	iOS Called if there was an error Android Will retry automatically upon a stable network connection.
`callback` (Web)	Function	Callback to be fired when the list of tags has been removed. The first parameter of the callback is an array of the tags that were deleted.

//Returns a Promise resolving with the object key-pair of the tag you deleted, 
//or rejected with an error.

//All examples are valid.

OneSignal.push(function() {
  OneSignal.deleteTags(["key1", "key2"], function(tagsDeleted) {
    // Callback called when tags have been deleted    
  });
});

OneSignal.push(function() {
  OneSignal.deleteTags(["key1", "key2"]).then(function(tagsDeleted) {
  });
});

Collection<String> tempList = new ArrayList<String>();
tempList.add(key);
OneSignal.deleteTags(tempList);

OneSignal.deleteTags(["key1", "key2"])

[OneSignal deleteTags:@[@"key1", @"key2"]];

OneSignal.Default.DeleteTags(new[] { "tag5", "tag6" });

OneSignal.deleteTags(["key1", "key2"]);

window.plugins.OneSignal.deleteTags(["key1", "key2"]);

await OneSignal.shared.deleteTags(["test_key_1", "test_key_2"]);

OneSignal.Current.DeleteTags(new List<string>() {"TestKey2", "TestKey3" })

OneSignal.DeleteTags({"key1", "key2"})

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)
    })
})

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

v3-4 SDK Data Tag SDK Methods

SDK Tagging Methods

`sendTag` Method

`sendTags` Method

`getTags` Method

`deleteTag` Method

`deleteTags` Method

Tagging Examples

Tag Based on Browser or Operating System

Get and Delete All Tags

​SDK Tagging Methods

​sendTag Method

​sendTags Method

​getTags Method

​deleteTag Method

​deleteTags Method

​Tagging Examples

​Tag Based on Browser or Operating System

​Get and Delete All Tags

SDK Tagging Methods

`sendTag` Method

`sendTags` Method

`getTags` Method

`deleteTag` Method

`deleteTags` Method

Tagging Examples

Tag Based on Browser or Operating System

Get and Delete All Tags