OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Data Tag SDK Implementation

Available options to add Data Tags to devices with OneSignal.

OneSignal tags are custom key : value pairs of string or number data that can be added to devices through our SDK, server-side API, or List Upload.

Tags should be added as string data, but any numbers/integers/decimals will be detected automatically on our backend and available for use.

Quick Reference

Details

SDK Tagging Methods

Methods available through our Client-Side SDK. Generally this is the recommended way to add data tags. See our Tagging Examples

Server Side Tagging Methods

API Edit device - Update tags using the OneSignal player_id
API Edit tags with external user id - Update tags using your Custom User ID (external_user_id).

CSV List Upload

Upload a CSV of user data through the OneSignal Dashboard with the player_id or external_user_id.

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.

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.SendTag("key", "value");
OneSignal.sendTag("key", "value");
window.plugins.OneSignal.sendTag("key", "value");
await OneSignal.shared.sendTag("test", "value");
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.

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.SendTags(new Dictionary<string, string>() { {"UnityTestKey2", "value2"}, {"UnityTestKey3", "value3"} });
OneSignal.sendTags({key: "value", key2: "value2"});
window.plugins.OneSignal.sendTags({key: "value", key2: "value2"});
await OneSignal.shared.sendTags({"test_key_1" : "test_value_1", "test_key_2" : "test_value_2"});
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);
}];
void SomeMethod() {
        OneSignal.GetTags(TagsReceived);
    }

    private void TagsReceived(Dictionary<string, object> tags) {
        foreach (var tag in tags)
            print(tag.Key + ":" + tag.Value);
    }
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.DeleteTag("key");
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.DeleteTags(new List<string>() {"UnityTestKey2", "UnityTestKey3" })
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 Tagging FAQ for common questions.

Device is Offline

Android Mobile SDKs have a feature which automatically handle offline support, and will retry adding the tag upon detecting a stable internet connection.

iOS Mobile SDK provides a callback for you to handle this case.

Web SDK, the user must be subscribed before the tag is added to the device record. Once the user registers, the tags will automatically be sent to our server as long as the page session is the same (the user has not navigated to another page).

Free Plan with 10 Tags

If you encounter a "10 tags" error, it means that the user's device has reached 10 tags, and you need to either delete some tags, or upgrade to a paid OneSignal plan in order to add more.

It's important to note that on Android devices using any of our mobile SDKs, the tags can be cached, and they will need to be deleted in order to add more.

You can check for tags with our getTags() method and delete the tags you don't need with our deleteTags() method.

Troubleshooting Methods

If you are having issues, plug the device into your IDE and use our setLogLevel SDK method set to Verbose. Then attempt to reproduce the issue you are seeing. This will help log any issues to your IDE console to debug.

Updated 19 days ago



Data Tag SDK Implementation


Available options to add Data Tags to devices with OneSignal.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.