# Теги
Теги — один из самых полезных инструментов, предлагаемых Pushwoosh, который открывает доступ к широкому спектру сложных функций. Используя теги, вы можете сегментировать свою аудиторию и отправлять целевые push-уведомления определенным пользователям на основе их атрибутов.
Теги могут содержать любые произвольные данные, связанные с конкретным пользователем или устройством. Эти данные могут включать имена пользователей, идентификаторы, города, любимые футбольные команды, предпочитаемые категории новостей или любую другую релевантную информацию о ваших пользователях.
## Выбор тегов для использования
Начните с определения потребностей вашего бизнеса и того, как вы хотите сегментировать свою аудиторию. Учитывайте такие факторы, как возраст, местоположение, история покупок в приложении или любые другие релевантные критерии для таргетинга пользователей.
## Значения тегов
Значения тегов помогут вам сделать ваши push-кампании умнее. Каждый тег способен хранить _практически неограниченное количество значений_. По сути, это означает, что одного тега будет достаточно для записи определенного типа информации о каждом конечном пользователе в вашей базе данных.
Для каждой учетной записи доступно лишь несколько тегов, но, учитывая практически бесконечное пространство для каждого тега, всего пары тегов достаточно, чтобы собрать огромное количество информации о ваших пользователях и настроить очень сложные шаблоны таргетинга.
## Типы тегов
* **Integer** — используется для целочисленных данных (количество внутриигровой валюты, достигнутый уровень, возраст).
* **String** — используется для строковых значений (имя пользователя, e-mail, идентификаторы).
* **List** — то же, что и тип String, но у каждого пользователя может быть установлено несколько значений одновременно (музыкальные предпочтения, категории новостей, предпочтения в кухне).
* **Boolean** — логический тип тега (true / false).
* **Date** — используется для календарных дат. По сути, это тег целочисленного типа, который хранит временные метки Unix Epoch (автоматически преобразуемые из/в григорианскую дату).
* **Price** — позволяет устанавливать значения в соответствии с указанной валютой в формате «\*.XX» [Узнать больше](https://ru.wikipedia.org/wiki/ISO_4217).
* **Version** — используется для версионирования. Пример допустимого формата: w.x.y.z (Major.Minor.Patch.Build). Максимальное значение для каждой части версии — 9999, поэтому максимальный номер версии не может быть больше 9999.9999.9999.9999.
### Операторы тегов
Каждый тип тега имеет определенный набор применимых **операторов**. Операторы тегов определяют отношение между тегом и его значениями для целей сегментации.
* Операторы тега Integer: `is`, `is not`, `are`, `not in`, `not set`, `any`
* Операторы тега String: `is`, `is not`, `are`, `not in`, `not set`, `any`
* Операторы тега List: `in`, `not in`, `not set`, `any`
* Операторы тега Boolean: `is` (true/false), `not set`, `any`
* Операторы тега Date: `exactly on`, `on or after`, `on or before`, `between`, `not set`, `any`
* Операторы тега Price: `is`, `is not`, `greater or equals`, `less or equals`, `between`, `in`, `not in`, `not set`, `any`
* Операторы тега Version: `is`, `is not`, `greater or equals`, `less or equals`, `between`, `in`, `not in`, `not set`, `any`
## Область действия тега: общая и пользовательская
При создании тега вы выбираете, как будут храниться его значения:
- **General** (по умолчанию, `user_specific: false`): значение тега хранится для каждого устройства (HWID). Каждое устройство одного и того же пользователя может иметь разное значение независимо от других.
- **User-specific** (`user_specific: true`): значение тега хранится для каждого пользователя (UserID). При установке через UserID значение применяется ко всем устройствам пользователя одновременно. Полезно для атрибутов, которые принадлежат человеку, а не конкретному устройству: уровень подписки, баллы лояльности, предпочитаемый язык.
### Пример
У пользователя установлены iOS и Android версии вашего приложения. Установка тега `subscription_tier` в значение `"premium"` через его UserID немедленно применит его к обоим устройствам. С общим тегом вам пришлось бы устанавливать его для каждого устройства отдельно.
```javascript title="Пример: установка пользовательского тега через UserID"
{
"request":{
"application": "XXXXX-XXXXX",
"userId": "the id of a specific user",
"tags": {
"subscription_tier": "premium",
"loyalty_points": 350
}
}
}
```
## Теги по умолчанию
Эти теги доступны в Pushwoosh "из коробки", поэтому вам не нужно (и, на самом деле, не следует) устанавливать их вручную. Большинство из них устанавливаются из приложения и отправляются на наш сервер через вызовы API, такие как [`registerDevice`](/ru/developer/api-reference/device-api/), а некоторые устанавливаются самим сервером.
| Название | Тип | Где устанавливается | Описание - |
| Application Version | Version | SDK | Текущая версия приложения, установленная на устройстве - |
| Browser Type | String | SDK | Когда устройство регистрируется для вашего веб-проекта, его тип — мобильный или десктопный — отслеживается автоматически - |
| City | String | Server | Последнее зарегистрированное географическое местоположение устройства - |
| Country | String | Server | Последнее зарегистрированное географическое местоположение устройства - |
| Device Model | String | SDK | Указывает модель устройства, на котором установлено приложение - |
- |
| First Install | Date | Server | Указывает время, когда устройство было впервые зарегистрировано для получения уведомлений - |
| In-App Product | List | SDK | Продукты, купленные пользователем в приложении - |
| Last In-App Purchase Date | Date | SDK | Дата последней покупки в приложении, совершенной на устройстве - |
- |
| Language | String | SDK | Двухбуквенная строчная аббревиатура локали устройства в соответствии с ISO-639-1; берется из настроек устройства - |
| Last Application Open | Date | Server | Время последнего запуска приложения на устройстве - |
| Last Email Open | Date | Server | Дата, когда с email-адреса устройства было в последний раз зарегистрировано событие открытия письма - |
| Last Email Open Message Code | String | Server | [Код сообщения](/ru/developer/api-reference/api-identifiers#message-code) последнего открытого письма (формат `XXXX-XXXXXXXX-XXXXXXXX`). Обновляется при каждом событии [`PW_EmailOpen`](/ru/product/audience-data-and-segmentation/events/default-events/#pw_emailopen). Используйте его для сегментации получателей определенной email-кампании по тем, кто ее открыл |
| Last Email Click | Date | Server | Дата, когда с email-адреса устройства был в последний раз зарегистрирован клик по ссылке в письме - |
| Last Email Click Message Code | String | Server | [Код сообщения](/ru/developer/api-reference/api-identifiers#message-code) последнего письма, в котором была нажата ссылка (формат `XXXX-XXXXXXXX-XXXXXXXX`). Обновляется при каждом событии [`PW_EmailLinkClicked`](/ru/product/audience-data-and-segmentation/events/default-events/#pw_emaillinkclicked). Используйте его для сегментации получателей определенной email-кампании по тем, кто нажал на ссылку |
| Last Email Confirm | Date | Server | Дата последнего подтверждения подписки Double Opt-In для email-адреса устройства - |
- |
| Bounced Email | Date | Server | Дата, когда для этого email-адреса произошел hard bounce. Хранится в виде даты для включения сегментации по времени, например, для исключения пользователей с недавними возвратами - |
| Unsubscribed Emails | Boolean | SDK | Указывает, отписался ли пользователь от получения писем от вашего приложения - |
| OS Version | Version | SDK | Версия операционной системы, работающей на устройстве - |
| Platform | String | SDK | Платформа, на которой пользователь использует ваш проект. |
| Push Alerts Enabled | Boolean | SDK | Указывает, разрешены ли push-уведомления в настройках устройства - |
| SDK Version | Version | SDK | Версия Pushwoosh SDK, реализованная на устройстве - |
## Пользовательские теги
Здесь вступает в игру ваша креативность для достижения конкретных бизнес-целей. Пользовательские теги могут быть созданы на основе логики сегментации или шаблона таргетинга, которые подходят для ваших уникальных бизнес-потребностей. Сотрудничайте с вашей маркетинговой командой, чтобы определить дополнительные пользовательские теги, необходимые для ваших кампаний.
### Как настроить пользовательский тег
Вы можете добавить новый тег в [Pushwoosh Control Panel](/ru/product/audience-data-and-segmentation/user-data-tags/tags) или использовать метод [`/addTag`](/ru/developer/api-reference/tags#addtag).
#### addTag
`POST` `https://api.pushwoosh.com/json/1.3/addTag`
Создает тег в вашей учетной записи.
#### Тело запроса
| Название | Тип | Описание - |
| auth* | string | Токен доступа к API из Pushwoosh Control Panel. - |
| tag* | object | Параметры тега. - |
| tag.name* | string | Название тега. - |
| tag.type* | integer | Тип тега. Возможные значения см. ниже. - |
| tag.user\_specific | boolean | Если `true`, значение тега хранится на уровне пользователя и является общим для всех его устройств при установке по UserID. Если `false` (по умолчанию), тег является тегом уровня устройства и устанавливается для каждого HWID. |
```javascript
{
"status_code": 200,
"status_message": "OK",
"response": {
"result": true
}
}
```
```javascript title="Пример"
{
"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)
}
}
}
```
**Возможные типы значений тегов:**
* 1 - Integer
* 2 - String
* 3 - List
* 4 - Date
* 5 - Boolean
* 6 - Decimal. Пример: 19.95
* 7 - Version. Пример: "1.0.0.0"
### Как собирать информацию от пользователей
После того как вы добавили и настроили тег, он готов к сбору информации от ваших пользователей. Выполните следующие шаги для его реализации:
1. Интегрируйте [Pushwoosh SDK](/ru/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) в свой проект, следуя соответствующему руководству по интеграции.
2. Используйте функцию [`setTags`](/ru/developer/api-reference/device-api/#settags) для присвоения тегов и сбора данных пользователей.
Ниже приведены примеры реализации для различных фреймворков с использованием функции [`setTags`](/ru/developer/api-reference/device-api/#settags).
```objective-c
NSDictionary *tags = @{
@"Alias" : aliasField.text,
@"FavNumber" : @([favNumField.text intValue]),
@"price" : [PWTags incrementalTagWithInteger:5],
@"List" : @[ @"Item1", @"Item2", @"Item3" ]
};
[[PushNotificationManager pushManager] setTags:tags];
```
[Документация](https://pushwoosh.github.io/pushwoosh-ios-sdk/PushwooshiOS/documentation/pushwooshframework/pushwoosh/settags(_:)/)
```java
pushwoosh.setTags(Tags.intTag("intTag", 42));
```
[Документация](https://pushwoosh.github.io/pushwoosh-android-sdk/pushwoosh/com.pushwoosh/-pushwoosh/set-tags.html)
```
PushNotification.prototype.setTags = function( config, success, fail )
```
[Документация](/ru/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/cordova-plugin-api-reference/#settags)
```dart
Future setTags(Map tags) async {
await _channel.invokeMethod("setTags", {"tags" : tags});
}
```
[Документация](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"]
});
```
[Документация](https://github.com/Pushwoosh/pushwoosh-react-native-plugin/blob/master/docs/README.md#settags)
##### **SetIntTag**
Устанавливает тег типа Integer для устройства.
```csharp
public virtual void SetIntTag(string tagName, int tagValue)
```
##### **SetStringTag**
Устанавливает тег типа String для устройства.
```csharp
public virtual void SetStringTag(string tagName, string tagValue)
```
##### **SetListTag**
Устанавливает тег типа List для устройства.
```csharp
public virtual void SetListTag(string tagName, List
```cpp
FPushwooshModule& pushwoosh = FPushwooshModule::Get();
pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }");
```
[Документация](https://github.com/Pushwoosh/pushwoosh-unreal-engine/blob/master/Plugins/Pushwoosh/Documentation/README.md#settags)
```javascript
Pushwoosh.setTags({ "key": keyValue, "value": inputValue });
```
[Документация](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];
```
[Документация](https://github.com/Pushwoosh/pushwoosh-dotnet/blob/c40c0fd60cb5fe5c5016c46d677a779a5600f45f/PushwooshSDK.DotNet.iOS.Bindings/PushwooshFramework.xcframework/ios-arm64/PushwooshFramework.framework/Headers/PushNotificationManager.h#L380)
**Входные параметры**
**Tags** – Список записей тегов, содержащих `TagName` и `TagValue`.
- `TagName` всегда должен быть типа **Text**.
- `TagValue` может быть **Text, Integer, Boolean, Date** и т.д.
[Узнать больше](/ru/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/pushwoosh-outsystems-plugin-client-actions#settags)
### Установка тегов через API
Хотя в большинстве случаев (99%) теги устанавливаются из приложения, вы также можете устанавливать теги через API Pushwoosh. Ниже приведен пример типичного запроса к эндпоинту [`/setTags`](/ru/developer/api-reference/device-api#settags):
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
}
}
}
```
[Для получения дополнительной информации обратитесь к документации API setTags](/ru/developer/api-reference/device-api/#settags)
## Использование тега **City** по умолчанию
Местоположение устройства определяется на основе его IP-адреса в момент последнего запуска вашего приложения на этом устройстве. GeoIP передает данные о местоположении в Pushwoosh, и Pushwoosh сохраняет полученное от GeoIP местоположение как значение тега City для конкретного устройства.
В некоторых случаях местоположение, предоставленное GeoIP, отличается от названия города — например, когда оно относится к району города или другой административной единице. Пожалуйста, будьте внимательны при использовании тега City по умолчанию для целей сегментации: убедитесь, что вы выбрали правильные значения.
Например, если вы собираетесь таргетировать пользователей из Мюнхена, вам придется охватить его несколькими значениями тега City, включая сам "Munich" (со всеми соответствующими значениями, такими как различные варианты написания, которые могут быть возвращены GeoIP и сохранены как значения тега) и несколько близлежащих районов.