Tags

Tags are one of the most useful tools Pushwoosh offers, enabling a range of sophisticated functionality. By using tags, you can segment your audience and send targeted push notifications to specific users based on their attributes.

Tags can contain any arbitrary data associated with a particular user or device. This data might include usernames, IDs, cities, favorite football teams, preferred news categories, or any other relevant information about your users.

Deciding which tags to use

Start by identifying your business needs and determining how you want to segment your audience. Consider factors such as age, location, in-app purchase history, or any other relevant criteria for targeting users.

Tip

The marketing team may need to be involved in this process to help decide which tags best align with your marketing goals and audience segmentation strategies.

Tag values

Tag values can help you make your push campaigns smarter. Each tag is capable of storing nearly limitless number of values. Basically, this means that one tag would be enough to record a specific type of information about each end-user in your database.

Types of tags

• Integer — used for the integer data (amount of in-game cash acquired, level achieved, age).
• String — used for string values (username, e-mail, identifiers).
• List — the same as String type, but each user may have multiple values set simultaneously (music preferences, news categories, cuisine preferences).
• Boolean — true / false type of Tag.
• Date — used for calendar dates. Basically, this is an integer type tag which stores Unix Epoch timestamps (automatically converted from/into Gregorian date).
• Price — allows to set values according to specified currency in the “*.XX” format Learn more.
• Version — used for versioning. The example of allowed format is w.x.y.z (Major.Minor.Patch.Build). Max value for each version part is 9999, so the max version number cannot be greater than 9999.9999.9999.9999.

Tag operators

Each Tag type has a specific set of operators applicable. Tag operators define the relationship between the Tag and its values for segmentation purposes.

• Integer Tag operators: is, is not, are, not in, not set, any
• String Tag operators: is, is not, are, not in, not set, any
• List Tag operators: in, not in, not set, any
• Boolean Tag operators: is (true/false), not set, any
• Date Tag operators: exactly on, on or after, on or before, between, not set, any
• Price Tag operators: is, is not, greater or equals, less or equals, between, in, not in, not set, any
• Version Tag operators: is, is not, greater or equals, less or equals, between, in, not in, not set, any

Note

“Not set” and “any” operators are available for all types of Tags.

Tag scope: General vs User-specific

When creating a tag, you choose how its values are stored:

• General (user_specific: false, the default for /addTag): the tag value is stored per device (HWID). Each device of the same user can hold a different value independently.
• User-specific (user_specific: true, the default in the Control Panel form and for tags created automatically by setTags): the tag value is stored per user (UserID). When set via UserID, the value is applied to all of the user’s devices at once. Useful for attributes that belong to the person, not a particular device: subscription tier, loyalty points, preferred language.

Example

A user has both the iOS and Android versions of your app installed. Setting a subscription_tier tag to "premium" via their UserID applies it to both devices immediately. With a General tag you would need to set it per device separately.

Example: set a user-specific tag via UserID

{
   "request":{
      "application": "XXXXX-XXXXX",
      "userId": "the id of a specific user",
      "tags": {
           "subscription_tier": "premium",
           "loyalty_points": 350
      }
   }
}

Default tags

These tags are available by Pushwoosh out-of-the-box, so you don’t have to (and, in fact, should not) set them manually. Most of them are set from the application and sent over to our server via registerDevice and other API calls, and some are set by the server itself. SMS Marketing Consent and Viber Marketing Consent are an exception. Your developers set them with setTags when a person agrees to or declines marketing messages.

Name	Type	Where it’s set	Description
Application Version	Version	SDK	Current version of the app installed on a device
Browser Type	String	SDK	When a device is registered for your web project, its type – mobile or desktop – is tracked automatically
City	String	Server	Latest registered geographical location of a device
Country	String	Server	Latest registered geographical location of a device
Device Model	String	SDK	Indicates the device model whereon the app is installed
First Install	Date	Server	Indicates the time when a device was registered for notifications for the first time
In-app Product	List	SDK	The in-app products purchased by a user of the app
Last In-app Purchase date	Date	SDK	The date of the latest in-app purchase made on a device
Language	String	SDK	Two-letter lowercase abbreviation of a device’s locale according to ISO-639-1; taken from device settings
Last Application Open	Date	Server	The time of the most recent app launch on a device
Last Email Open	Date	Server	The date when the device’s email address most recently registered an email open event
Last Email Open Message Code	String	Server	Message code of the most recently opened email (format XXXX-XXXXXXXX-XXXXXXXX). Updated on each PW_EmailOpen event. Use it to segment recipients of a specific email campaign by who opened it
Last Email Click	Date	Server	The date when the device’s email address most recently registered an email link click
Last Email Click Message Code	String	Server	Message code of the most recent email in which a link was clicked (format XXXX-XXXXXXXX-XXXXXXXX). Updated on each PW_EmailLinkClicked event. Use it to segment recipients of a specific email campaign by who clicked
Last Email Confirm	Date	Server	The date of the most recent Double Opt-In subscription confirmation for the device’s email address
Bounced Email	Date	Server	The date when a hard bounce occurred for this email address. Stored as Date to enable time-based segmentation, for example, to exclude users with recent bounces
Unsubscribed Emails	Boolean	SDK	Indicates whether a user has unsubscribed from receiving emails from your app
SMS Marketing Consent	Boolean	Server, setTags	Whether the SMS subscriber agreed to marketing SMS: true agreed, false opted out, no value unknown. Learn more
Viber Marketing Consent	Boolean	Server, setTags	Whether the Viber subscriber agreed to marketing Viber messages: true agreed, false opted out, no value unknown. Learn more
OS Version	Version	SDK	The version of an operating system running on a device
Platform	String	SDK	The platform on which the user is using your project.
Push Alerts Enabled	Boolean	SDK	Indicates whether push alerts are allowed in device settings
Push Permission Status	String	SDK	State of the push permission on a device, such as not_determined, provisional, granted_explicit, or denied. Reserved: you can’t create a custom tag with this name. Learn more
SDK Version	Version	SDK	The version of the Pushwoosh SDK implemented on a device
Live Activity ID	List	SDK	Used to manage live activities by associating a Live Activity ID with the device. Automatically cleaned up after 12 hours. Reserved: you can’t create a custom tag with this name.
WhatsApp Session Expires At	Date	Server	Holds the current 24-hour customer service window opened by the customer’s last inbound WhatsApp message. Set automatically on each inbound message. Reserved: you can’t create a custom tag with this name. Stores only the current window, no history.
WhatsApp Ad Click ID	String	Server	The Click-to-WhatsApp ad click ID (ctwa_clid) from the referral of an inbound WhatsApp message. Meta sends it once, on the message that opens the conversation. A newer click overwrites it together with WhatsApp Ad Click Date. A replayed or out-of-order webhook doesn’t roll it back.
WhatsApp Ad Click Date	Date	Server	The time of the click recorded in WhatsApp Ad Click ID. Updated together with it: a newer click overwrites the previous date.

Custom tags

This is where your creativity comes in to achieve your specific business goals. Custom tags can be created based on the segmentation logic or targeting pattern that is appropriate for your unique business needs. Collaborate with your marketing team to define the additional custom tags necessary for your campaigns.

How to set up a custom tag

Creating a tag ahead of time is optional. Sending a new tag name via setTags creates it automatically, with the type inferred from the value:

• A whole number becomes Integer.
• A number with a fractional part, such as 4.99, becomes Price. A number like 5.0 becomes Integer.
• A string becomes String, or Date for a recognized date-time format such as 2024-10-02 22:11.
• A string that holds a number, true or false, or a JSON array is typed by its content, so "42" becomes Integer, not String.
• An array becomes List.
• A boolean becomes Boolean.

Event attributes don’t read a string by its content, so "42" sent in an event becomes String. See Events created automatically.

An auto-created tag is always User-specific (user_specific: true). Add the tag explicitly first, via the Control Panel or /addTag, for a Version tag, which auto-creation can’t infer, or for a General tag.

Tag auto-creation is enabled by default for the vast majority of accounts. If setTags doesn’t create a new tag as expected, contact Pushwoosh Support to check whether it’s been turned off for your account.

You can add a new tag in the Pushwoosh Control Panel or use the /addTag method.

addTag

POST https://api.pushwoosh.com/json/1.3/addTag

Creates a tag in your account.

Request Body

Name	Type	Description
auth*	string	API access token from Pushwoosh Control Panel.
tag*	object	Tag parameters.
tag.name*	string	Tag name.
tag.type*	integer	Tag type. See possible values below.
tag.user_specific	boolean	When true, the tag value is stored at the user level and shared across all of a user’s devices when set by UserID. When false (default), the tag is device-level and set per HWID.

200

{
    "status_code": 200,
    "status_message": "OK",
    "response": {
        "result": true
    }
}

Example

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // required, API access token from Pushwoosh Control Panel
    "tag": {
      "name": "TAG_NAME",    // required
      "type": 1,             // required, see possible values below
      "user_specific": false // optional. true = user-level; false = device-level (default)
    }
  }
}

Possible tag value types:

• 1 - Integer
• 2 - String
• 3 - List
• 4 - Date
• 5 - Boolean
• 6 - Decimal. Ex: 19.95
• 7 - Version. Ex: “1.0.0.0”

How to collect information from users

Once you’ve added and configured a tag, it’s ready to start collecting information from your users. Follow these steps to implement it:

1. Integrate the Pushwoosh SDK into your project by following the relevant integration guide.
2. Use the setTags function to assign tags and collect user data.

Below are implementation examples for different frameworks using the setTags function.

iOS Native

iOS Native

NSDictionary *tags = @{
    @"Alias" : aliasField.text,
    @"FavNumber" : @([favNumField.text intValue]),
    @"price" : [PWTags incrementalTagWithInteger:5],
    @"List" : @[ @"Item1", @"Item2", @"Item3" ]
};

[[PushNotificationManager pushManager] setTags:tags];

Documentation

Android Native

Android Native

pushwoosh.setTags(Tags.intTag("intTag", 42));

Documentation

Cordova

Cordova

PushNotification.prototype.setTags = function(  config, success, fail  )

Documentation

Flutter

Flutter

Future<void> setTags(Map tags) async {
  await _channel.invokeMethod("setTags", {"tags" : tags});
}

Documentation

React Native

React Native

pushNotification.setTags({
    "string_tag" : "Hello world",
    "int_tag" : 42,
    "list_tag":["hello", "world"]
});

Documentation

Unity

Unity

SetIntTag

Sets an Integer Tag for the device.

public virtual void SetIntTag(string tagName, int tagValue)

SetStringTag

Sets a String Tag for the device.

public virtual void SetStringTag(string tagName, string tagValue)

SetListTag

Sets a List Tag for the device.

public virtual void SetListTag(string tagName, List<object> tagValues)

Documentation

Unreal Engine

Unreal Engine

FPushwooshModule& pushwoosh = FPushwooshModule::Get();
pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }");

Documentation

Expo

Expo

Pushwoosh.setTags({ "key": keyValue, "value": inputValue });

Documentation

.NET MAUI

.NET MAUI

NSDictionary *tags = @{
    @"Alias" : aliasField.text,
    @"FavNumber" : @([favNumField.text intValue]),
    @"price" : [PWTags incrementalTagWithInteger:5],
    @"List" : @[ @"Item1", @"Item2", @"Item3" ]
};
[[PushNotificationManager pushManager] setTags:tags];

Documentation

Outsystems

Outsystems

Input parameters Tags – A list of tag records containing TagName and TagValue.

• TagName must always be of type Text.
• TagValue can be Text, Integer, Boolean, Date, etc.

Learn more

Setting tags via API

While in most cases (99%), tags are set from the application, you can also set tags via Pushwoosh API. Below is an example of a typical request to the /setTags endpoint:

POST https://api.pushwoosh.com/json/1.3/setTags

{
   "request": {
      "application": "XXXXX-XXXXX", // required, Pushwoosh application code
      "hwid": "8f65bXXXf378eXXXbeceXXX4e153XXX2", // required, hardware device ID used in /registerDevice API
      "tags": { // required
           "StringTag": "string value", // Example of a string tag
           "IntegerTag": 42, // Example of an integer tag
           "ListTag": ["string1", "string2"], // Example of a list tag
           "DateTag": "2024-10-02 22:11", // Note: time must be in UTC
           "BooleanTag": true // Valid values: true, false
      }
   }
}

For further details, refer to the setTags API documentation

Note

A tag name that doesn’t exist yet is created automatically the first time setTags sends it, with the type inferred from the value. For the type rules and what to do if a tag isn’t created, see How to set up a custom tag.

An auto-created tag is always User-specific. To create a Version tag, which auto-creation can’t infer, or a General tag, add it explicitly first, via the Control Panel or /addTag.

Using the default City tag

Device’s location is determined based on its IP address at the moment your app was launched on that device for the last time. GeoIP submits the location data to Pushwoosh, and Pushwoosh saves the location received from GeoIP as a City tag value for a particular device.

In some cases, the location submitted by the GeoIP differs from the city name — for example, when it refers to an area of a city or other administrative unit. Please be careful when using the default City tag for segmentation purposes: make sure to select the proper values.

For example, if you’re going to target users from Munich, you have to cover it with a bunch of City tag values, including “Munich” itself (with all the corresponding values, such as different variants of spelling which could be returned by GeoIP and saved as tag values) and several nearby areas.

Tip

Before creating a Segment via the API, check the values your users have on their devices via /getTagStats request.