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. Use sendTags if you need to set 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.

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

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

`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.

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

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

`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.

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

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

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.

`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.

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

OneSignal.push(function() {
  OneSignal.deleteTag("tagKey");
});

`deleteTags` Method

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

Parameter	Type	Description
`keys`	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.

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

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

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:

Auto-Segment By Subscription Page - tag users based on the page they subscribed on.
Auto-Segment By Page Visit - tag users based on how many times they visit certain topics of your app or site.
Auto-Segment By Notification Topic - tag users based on types of notifications they click.
Abandoned Cart - remind users x amount of time after they added an item to the cart.

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.