整数 (Integer) — 用于整数数据（获得的游戏内现金数量、达到的级别、年龄）。
字符串 (String) — 用于字符串值（用户名、电子邮件、标识符）。
列表 (List) — 与字符串类型相同，但每个用户可以同时设置多个值（音乐偏好、新闻类别、美食偏好）。
布尔值 (Boolean) — true / false 类型的标签。
日期 (Date) — 用于日历日期。基本上，这是一种整数类型的标签，存储 Unix Epoch 时间戳（自动从/转换为公历日期）。
价格 (Price) — 允许根据指定货币以“*.XX”格式设置值了解更多。
版本 (Version) — 用于版本控制。允许的格式示例为 w.x.y.z (Major.Minor.Patch.Build)。每个版本部分的最大值为 9999，因此最大版本号不能大于 9999.9999.9999.9999。

标签操作符

每种标签类型都有一组特定的操作符适用。标签操作符定义了标签与其值之间的关系，用于细分目的。

整数标签操作符：is、is not、are、not in、not set、any
字符串标签操作符：is、is not、are、not in、not set、any
列表标签操作符：in、not in、not set、any
布尔标签操作符：is (true/false)、not set、any
日期标签操作符：exactly on、on or after、on or before、between、not set、any
价格标签操作符：is、is not、greater or equals、less or equals、between、in、not in、not set、any
版本标签操作符：is、is not、greater or equals、less or equals、between、in、not in、not set、any

标签范围：通用 vs 用户特定

创建标签时，您可以选择其值的存储方式：

General (user_specific: false，/addTag 的默认值)：标签值按设备 (HWID) 存储。同一用户的每个设备可以独立持有不同的值。
User-specific (user_specific: true，控制面板表单以及通过 setTags 自动创建的标签的默认值)：标签值按用户 (UserID) 存储。通过 UserID 设置时，该值会一次性应用于该用户的所有设备。适用于属于个人而非特定设备的属性：订阅等级、忠诚度积分、首选语言。

示例

一个用户同时安装了您的应用的 iOS 和 Android 版本。通过他们的 UserID 将 subscription_tier 标签设置为 "premium"，会立即将其应用于两个设备。如果使用 General 标签，您需要分别为每个设备进行设置。

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

默认标签

这些标签由 Pushwoosh 开箱即用提供，因此您不必（实际上也不应该）手动设置它们。它们中的大多数是从应用程序设置并通过 registerDevice 和其他 API 调用发送到我们的服务器的，还有一些是由服务器本身设置的。SMS Marketing Consent 和 Viber Marketing Consent 是例外。当用户同意或拒绝接收营销消息时，由您的开发人员通过 setTags 设置它们。

名称	类型	设置位置	描述
Application Version	版本	SDK	设备上安装的应用的当前版本
Browser Type	字符串	SDK	当设备为您的 Web 项目注册时，其类型——移动或桌面——会自动被跟踪
City	字符串	服务器	设备最新注册的地理位置
Country	字符串	服务器	设备最新注册的地理位置
Device Model	字符串	SDK	指示安装应用的设备型号
First Install	日期	服务器	指示设备首次注册通知的时间
In-app Product	列表	SDK	应用用户购买的应用内产品
Last In-app Purchase date	日期	SDK	设备上最近一次应用内购买的日期
Language	字符串	SDK	根据 ISO-639-1 标准的设备区域设置的双字母小写缩写；取自设备设置
Last Application Open	日期	服务器	设备上最近一次应用启动的时间
Last Email Open	日期	服务器	设备的电子邮件地址最近一次注册电子邮件打开事件的日期
Last Email Open Message Code	字符串	服务器	最近打开的电子邮件的消息代码（格式 `XXXX-XXXXXXXX-XXXXXXXX`）。每次 `PW_EmailOpen` 事件发生时更新。用它来按打开特定电子邮件活动的人来细分收件人
Last Email Click	日期	服务器	设备的电子邮件地址最近一次注册电子邮件链接点击的日期
Last Email Click Message Code	字符串	服务器	最近一次点击链接的电子邮件的消息代码（格式 `XXXX-XXXXXXXX-XXXXXXXX`）。每次 `PW_EmailLinkClicked` 事件发生时更新。用它来按点击特定电子邮件活动的人来细分收件人
Last Email Confirm	日期	服务器	设备电子邮件地址最近一次双重选择性加入订阅确认的日期
Bounced Email	日期	服务器	此电子邮件地址发生硬退信的日期。存储为日期以启用基于时间的细分，例如，排除最近有退信的用户
Unsubscribed Emails	布尔值	SDK	指示用户是否已退订接收来自您应用的电子邮件
SMS Marketing Consent	布尔值	服务器, setTags	SMS 订阅者是否同意接收营销短信：`true` 表示同意，`false` 表示已退订，无值表示未知。了解更多
Viber Marketing Consent	布尔值	服务器, setTags	Viber 订阅者是否同意接收 Viber 营销消息：`true` 表示同意，`false` 表示已退订，无值表示未知。了解更多
OS Version	版本	SDK	设备上运行的操作系统的版本
Platform	字符串	SDK	用户使用您项目的平台。
Push Alerts Enabled	布尔值	SDK	指示设备设置中是否允许推送提醒
SDK Version	版本	SDK	设备上实现的 Pushwoosh SDK 的版本
Live Activity ID	列表	SDK	通过将 Live Activity ID 与设备关联来管理实时活动。12 小时后自动清除。保留名称：您无法使用此名称创建自定义标签。
WhatsApp Session Expires At	日期	服务器	保存由客户最后一条入站 WhatsApp 消息开启的当前 24 小时客户服务窗口。每条入站消息都会自动设置该值。保留名称：您无法使用此名称创建自定义标签。仅存储当前窗口，不保留历史记录。
WhatsApp Ad Click ID	字符串	服务器	来自入站 WhatsApp 消息 referral 的 Click-to-WhatsApp 广告点击 ID (`ctwa_clid`)。Meta 只发送一次，即在开启对话的那条消息中。更新的点击会将其连同 `WhatsApp Ad Click Date` 一起覆盖。重放或乱序到达的 webhook 不会将其回滚。
WhatsApp Ad Click Date	日期	服务器	`WhatsApp Ad Click ID` 中记录的点击时间。与其一同更新：更新的点击会覆盖之前的日期。

自定义标签

在这里，您可以发挥创造力以实现您的特定业务目标。可以根据适合您独特业务需求的细分逻辑或目标模式创建自定义标签。与您的市场营销团队合作，定义您的活动所需的其他自定义标签。

如何设置自定义标签

提前创建标签是可选的。通过 setTags 发送一个新的标签名称会自动创建它，类型会根据值推断：

整数会变成整数类型。
带小数部分的数字（例如 4.99）会变成价格类型。像 5.0 这样的数字会变成整数类型。
字符串会变成字符串类型；对于可识别的日期时间格式（如 2024-10-02 22:11），则变成日期类型。
包含数字、true 或 false 或 JSON 数组的字符串会按其内容确定类型，因此 "42" 会变成整数类型，而不是字符串类型。
数组会变成列表类型。
布尔值会变成布尔类型。

事件属性不会根据字符串的内容确定类型，因此在事件中发送的 "42" 会变成字符串类型。请参阅自动创建的事件。

自动创建的标签始终是 User-specific (user_specific: true)。对于版本标签（自动创建无法推断），或者对于 General 标签，请先通过控制面板或 /addTag 明确添加标签。

绝大多数账户默认启用标签自动创建功能。如果 setTags 未能如预期创建新标签，请联系 Pushwoosh 支持以检查该功能是否已为您的账户关闭。

您可以在 Pushwoosh 控制面板中添加新标签，或使用 /addTag 方法。

addTag

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

在您的账户中创建一个标签。

请求体

名称	类型	描述
auth*	string	来自 Pushwoosh 控制面板的 API 访问令牌。
tag*	object	标签参数。
tag.name*	string	标签名称。
tag.type*	integer	标签类型。请参阅下面的可能值。
tag.user_specific	boolean	当为 `true` 时，标签值存储在用户级别，并通过 UserID 设置时在用户的所有设备间共享。当为 `false`（默认）时，标签是设备级别的，并按 HWID 设置。

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

{
  "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 - 整数
2 - 字符串
3 - 列表
4 - 日期
5 - 布尔值
6 - 小数。例如：19.95
7 - 版本。例如：“1.0.0.0”

如何从用户处收集信息

添加并配置标签后，它就可以开始从您的用户那里收集信息了。请按照以下步骤实施：

按照相关的集成指南，将 Pushwoosh SDK 集成到您的项目中。
使用 setTags 函数分配标签并收集用户数据。

以下是使用 setTags 函数针对不同框架的实现示例。

iOS Native

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

[[PushNotificationManager pushManager] setTags:tags];

文档

Android Native

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

文档

Cordova

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

文档

Flutter

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

文档

React Native

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

文档

Unity

SetIntTag

为设备设置一个整数标签。

public virtual void SetIntTag(string tagName, int tagValue)

SetStringTag

为设备设置一个字符串标签。

public virtual void SetStringTag(string tagName, string tagValue)

SetListTag

为设备设置一个列表标签。

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

文档

Unreal Engine

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

文档

Expo

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

文档

.NET MAUI

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

文档

Outsystems

输入参数 Tags – 包含 TagName 和 TagValue 的标签记录列表。

TagName 必须始终为文本类型。
TagValue 可以是文本、整数、布尔值、日期等。

了解更多

通过 API 设置标签

虽然在大多数情况 (99%) 下，标签是从应用程序设置的，但您也可以通过 Pushwoosh API 设置标签。以下是向 /setTags 端点发出的典型请求示例：

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

有关更多详细信息，请参阅 setTags API 文档

使用默认的 City 标签

设备的位置是根据其 IP 地址在您的应用在该设备上最后一次启动时确定的。GeoIP 将位置数据提交给 Pushwoosh，Pushwoosh 将从 GeoIP 收到的位置保存为特定设备的 City 标签值。

在某些情况下，GeoIP 提交的位置与城市名称不同——例如，当它指的是一个城市的某个区域或其他行政单位时。在使用默认的 City 标签进行细分时请务必小心：确保选择正确的值。

例如，如果您要定位来自慕尼黑的用户，您需要用一系列 City 标签值来覆盖它，包括“Munich”本身（以及所有相应的值，例如 GeoIP 可能返回并保存为标签值的不同拼写变体）和几个附近的区域。