# 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. ## 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. There are only a few tags available for each account, but considering the nearly-infinite space for each tag, just a couple of tags are enough to gather an enormous amount of information about your users and set up very complex targeting patterns. ## 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](https://en.wikipedia.org/wiki/ISO\_4217). * **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` ## Tag scope: General vs User-specific When creating a tag, you choose how its values are stored: - **General** (default, `user_specific: false`): 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 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. ```javascript title="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`](/developer/api-reference/device-api/) and other API calls, and some are set by the server itself. | 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](/developer/api-reference/api-identifiers#message-code) of the most recently opened email (format `XXXX-XXXXXXXX-XXXXXXXX`). Updated on each [`PW_EmailOpen`](/product/audience-data-and-segmentation/events/default-events/#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](/developer/api-reference/api-identifiers#message-code) of the most recent email in which a link was clicked (format `XXXX-XXXXXXXX-XXXXXXXX`). Updated on each [`PW_EmailLinkClicked`](/product/audience-data-and-segmentation/events/default-events/#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 | | 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 | | SDK Version | Version | SDK | The version of the Pushwoosh SDK implemented on a device | ## 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 You can add a new tag in the [Pushwoosh Control Panel](/product/audience-data-and-segmentation/user-data-tags/tags) or use the [`/addTag`](/developer/api-reference/tags#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. | ```javascript { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` ```javascript title="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](/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) into your project by following the relevant integration guide. 2. Use the [`setTags`](/developer/api-reference/device-api/#settags) function to assign tags and collect user data. Below are implementation examples for different frameworks using the [`setTags`](/developer/api-reference/device-api/#settags) function. ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [Documentation](https://pushwoosh.github.io/pushwoosh-ios-sdk/PushwooshiOS/documentation/pushwooshframework/pushwoosh/settags(_:)/) ```java pushwoosh.setTags(Tags.intTag("intTag", 42)); ``` [Documentation](https://pushwoosh.github.io/pushwoosh-android-sdk/pushwoosh/com.pushwoosh/-pushwoosh/set-tags.html) ``` PushNotification.prototype.setTags = function( config, success, fail ) ``` [Documentation](/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/cordova-plugin-api-reference/#settags) ```dart Future setTags(Map tags) async { await _channel.invokeMethod("setTags", {"tags" : tags}); } ``` [Documentation](https://pub.dev/documentation/pushwoosh_flutter/latest/pushwoosh_flutter/Pushwoosh/setTags.html) ```javascript pushNotification.setTags({ "string_tag" : "Hello world", "int_tag" : 42, "list_tag":["hello", "world"] }); ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-react-native-plugin/blob/master/docs/README.md#settags) ##### **SetIntTag** Sets an Integer Tag for the device. ```csharp public virtual void SetIntTag(string tagName, int tagValue) ``` ##### **SetStringTag** Sets a String Tag for the device. ```csharp public virtual void SetStringTag(string tagName, string tagValue) ``` ##### **SetListTag** Sets a List Tag for the device. ```csharp public virtual void SetListTag(string tagName, List tagValues) ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-unity/blob/master/Documentation/README.md#pushwoosh) ```cpp FPushwooshModule& pushwoosh = FPushwooshModule::Get(); pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }"); ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-unreal-engine/blob/master/Plugins/Pushwoosh/Documentation/README.md#settags) ```javascript Pushwoosh.setTags({ "key": keyValue, "value": inputValue }); ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-expo-plugin-sample/blob/main/app/_layout.tsx#L296C17-L296C76) ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [Documentation](https://github.com/Pushwoosh/pushwoosh-dotnet/blob/c40c0fd60cb5fe5c5016c46d677a779a5600f45f/PushwooshSDK.DotNet.iOS.Bindings/PushwooshFramework.xcframework/ios-arm64/PushwooshFramework.framework/Headers/PushNotificationManager.h#L380) **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](/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/pushwoosh-outsystems-plugin-client-actions#settags) ### 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`](/developer/api-reference/device-api#settags) endpoint: POST `https://api.pushwoosh.com/json/1.3/setTags` ```json { "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](/developer/api-reference/device-api/#settags) ## 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.