Log InSign Up

Data Tag SDK Methods

Available options to add Data Tags to devices with OneSignal.

Suggest Edits

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.

🚧

Not for User IDs

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 Tags FAQ for details.

ParameterTypeDescription
keyString, NSString*Key of your choosing to create or update
valueString, 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)OneSignalResultSuccessBlockiOS Called if there were no errors sending the tag.
onFailure(Optional)OneSignalFailureBlockiOS Called if there was an error.

Android Will retry automatically upon a stable network connection.
callback (Web)FunctionCall 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 Tags FAQ for details.

ParameterTypeDescription
keyValuesJSONObject, 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)OneSignalResultSuccessBlockiOS Called if there were no errors sending the tag.
onFailure(Optional)OneSignalFailureBlockiOS Called if there was an error.

Android Will retry automatically upon a stable network connection.
callback (Web)FunctionCall 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)
ParameterTypeDescription
tagsJSON Object of String dataContains key-value pairs retrieved from the OneSignal server.
successBlockOneSignalResultSuccessBlockCalled when tags are received from OneSignal's server.
onFailure(Optional)OneSignalFailureBlockCalled 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.

ParameterTypeDescription
keyString, NSString*Key to remove
onSuccess(Optional)OneSignalResultSuccessBlockiOS Called if there were no errors
onFailure(Optional)OneSignalFailureBlockiOS 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.

ParameterTypeDescription
keysArray, Collection, NSArray*Keys to remove.
onSuccess(Optional)OneSignalResultSuccessBlockiOS Called if there were no errors
onFailure(Optional)OneSignalFailureBlockiOS Called if there was an error

Android Will retry automatically upon a stable network connection.
callback (Web)FunctionCallback 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)
    })
})

Additional Guides

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

Troubleshooting

See our Tag Troubleshooting for details.

Updated about 1 year ago

What’s Next