# 标签 标签是 Pushwoosh 提供的最有用的工具之一，可实现一系列复杂的功能。通过使用标签，您可以细分受众，并根据用户的属性向特定用户发送有针对性的推送通知。 标签可以包含与特定用户或设备关联的任何任意数据。这些数据可能包括用户名、ID、城市、最喜欢的足球队、偏好的新闻类别或任何其他关于用户的相关信息。 ## 决定使用哪些标签 首先确定您的业务需求，并决定您希望如何细分受众。考虑年龄、位置、应用内购买历史或任何其他用于定位用户的相关标准等因素。 ## 标签值 标签值可以帮助您使推送营销活动更加智能。每个标签能够存储*几乎无限数量的值*。基本上，这意味着一个标签就足以记录数据库中每个最终用户的特定类型信息。 每个账户只有少数几个标签可用，但考虑到每个标签近乎无限的空间，仅用几个标签就足以收集关于您用户的大量信息，并设置非常复杂的目标定位模式。 ## 标签类型 * **Integer** — 用于整数数据（例如，获得的游戏内现金数量、达到的级别、年龄）。 * **String** — 用于字符串值（例如，用户名、电子邮件、标识符）。 * **List** — 与 String 类型相同，但每个用户可以同时设置多个值（例如，音乐偏好、新闻类别、美食偏好）。 * **Boolean** — true / false 类型的标签。 * **Date** — 用于日历日期。基本上，这是一个整数类型的标签，存储 Unix Epoch 时间戳（自动从/转换为公历日期）。 * **Price** — 允许根据“\*.XX”格式中指定的货币设置值 [了解更多](https://en.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` ## 标签范围：通用 vs. 用户特定 创建标签时，您可以选择其值的存储方式： - **通用** (默认, `user_specific: false`)：标签值按设备 (HWID) 存储。同一用户的每个设备可以独立持有不同的值。 - **用户特定** (`user_specific: true`)：标签值按用户 (UserID) 存储。通过 UserID 设置时，该值会立即应用于该用户的所有设备。适用于属于个人而非特定设备的属性：订阅等级、忠诚度积分、首选语言。 ### 示例 一个用户同时安装了您的应用的 iOS 和 Android 版本。通过他们的 UserID 将 `subscription_tier` 标签设置为 `"premium"`，会立即将其应用于两个设备。如果使用通用标签，您需要分别为每个设备进行设置。 ```javascript title="示例：通过 UserID 设置用户特定的标签" { "request":{ "application": "XXXXX-XXXXX", "userId": "the id of a specific user", "tags": { "subscription_tier": "premium", "loyalty_points": 350 } } } ``` ## 默认标签 这些标签由 Pushwoosh 开箱即用提供，因此您不必（实际上也不应该）手动设置它们。它们中的大多数是从应用程序设置并通过 [`registerDevice`](/zh/developer/api-reference/device-api/) 和其他 API 调用发送到我们的服务器的，还有一些是由服务器本身设置的。 | 名称 | 类型 | 设置位置 | 描述 | | ------------------------- | ------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application Version | Version | SDK | 设备上安装的应用的当前版本 | | Browser Type | String | SDK | 当设备为您的 Web 项目注册时，其类型——移动或桌面——会自动被跟踪 | | City | String | 服务器 | 设备最近注册的地理位置 | | Country | String | 服务器 | 设备最近注册的地理位置 | | Device Model | String | SDK | 指示应用安装的设备型号 | | First Install | Date | 服务器 | 指示设备首次注册通知的时间 | | In-App Product | List | SDK | 应用用户购买的应用内产品 | | Last In-App Purchase Date | Date | SDK | 设备上最近一次应用内购买的日期 | | Language | String | SDK | 根据 ISO-639-1 标准的设备区域设置的双字母小写缩写；取自设备设置 | | Last Application Open | Date | 服务器 | 设备上最近一次应用启动的时间 | | Last Email Open | Date | 服务器 | 设备的电子邮件地址最近注册电子邮件打开事件的日期 | | Last Email Open Message Code | String | 服务器 | 最近打开的电子邮件的[消息代码](/zh/developer/api-reference/api-identifiers#message-code)（格式 `XXXX-XXXXXXXX-XXXXXXXX`）。在每个 [`PW_EmailOpen`](/zh/product/audience-data-and-segmentation/events/default-events/#pw_emailopen) 事件上更新。用它来根据打开情况对特定电子邮件营销活动的收件人进行分群 | | Last Email Click | Date | 服务器 | 设备的电子邮件地址最近注册电子邮件链接点击的日期 | | Last Email Click Message Code | String | 服务器 | 最近点击链接的电子邮件的[消息代码](/zh/developer/api-reference/api-identifiers#message-code)（格式 `XXXX-XXXXXXXX-XXXXXXXX`）。在每个 [`PW_EmailLinkClicked`](/zh/product/audience-data-and-segmentation/events/default-events/#pw_emaillinkclicked) 事件上更新。用它来根据点击情况对特定电子邮件营销活动的收件人进行分群 | | Last Email Confirm | Date | 服务器 | 设备的电子邮件地址最近一次双重选择加入订阅确认的日期 | | Bounced Email | Date | 服务器 | 此电子邮件地址发生硬退信的日期。存储为日期以启用基于时间的细分，例如，排除最近有退信的用户 | | Unsubscribed Emails | Boolean | SDK | 指示用户是否已退订接收来自您应用的电子邮件 | | OS Version | Version | SDK | 设备上运行的操作系统的版本 | | Platform | String | SDK | 用户使用您项目的平台。 | | Push Alerts Enabled | Boolean | SDK | 指示设备设置中是否允许推送提醒 | | SDK Version | Version | SDK | 设备上实现的 Pushwoosh SDK 的版本 | ## 自定义标签 这是您发挥创造力以实现特定业务目标的地方。可以根据适合您独特业务需求的细分逻辑或目标模式创建自定义标签。与您的营销团队合作，定义您的营销活动所需的其他自定义标签。 ### 如何设置自定义标签 您可以在 [Pushwoosh 控制面板](/zh/product/audience-data-and-segmentation/user-data-tags/tags)中添加新标签，或使用 [`/addTag`](/zh/developer/api-reference/tags#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 设置。 | ```javascript { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` ```javascript title="示例" { "request": { "auth": "yxoPUlwqm…………pIyEX4H", // 必填，来自 Pushwoosh 控制面板的 API 访问令牌 "tag": { "name": "TAG_NAME", // 必填 "type": 1, // 必填，请参阅下面的可能值 "user_specific": false // 可选。true = 用户级别；false = 设备级别（默认） } } } ``` **可能的标签值类型：** * 1 - Integer * 2 - String * 3 - List * 4 - Date * 5 - Boolean * 6 - Decimal. Ex: 19.95 * 7 - Version. Ex: "1.0.0.0" ### 如何从用户处收集信息 添加并配置标签后，它就可以开始从您的用户那里收集信息了。请按照以下步骤实施： 1. 按照相关的集成指南，将 [Pushwoosh SDK](/zh/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) 集成到您的项目中。 2. 使用 [`setTags`](/zh/developer/api-reference/device-api/#settags) 函数分配标签并收集用户数据。 以下是使用 [`setTags`](/zh/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 ) ``` [文档](/zh/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 tagValues) ``` [文档](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\" ] }"); ``` [文档](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** 等。 [了解更多](/zh/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/pushwoosh-outsystems-plugin-client-actions#settags) ### 通过 API 设置标签 虽然在大多数情况（99%）下，标签是从应用程序设置的，但您也可以通过 Pushwoosh API 设置标签。以下是向 [`/setTags`](/zh/developer/api-reference/device-api#settags) 端点发出的典型请求示例： POST `https://api.pushwoosh.com/json/1.3/setTags` ```json { "request": { "application": "XXXXX-XXXXX", // 必填，Pushwoosh 应用代码 "hwid": "8f65bXXXf378eXXXbeceXXX4e153XXX2", // 必填，在 /registerDevice API 中使用的硬件设备 ID "tags": { // 必填 "StringTag": "string value", // 字符串标签示例 "IntegerTag": 42, // 整数标签示例 "ListTag": ["string1", "string2"], // 列表标签示例 "DateTag": "2024-10-02 22:11", // 注意：时间必须为 UTC "BooleanTag": true // 有效值：true, false } } } ``` [有关更多详细信息，请参阅 setTags API 文档](/zh/developer/api-reference/device-api/#settags) ## 使用默认的 **City** 标签 设备的位置是根据其上次启动您的应用时的 IP 地址确定的。GeoIP 将位置数据提交给 Pushwoosh，Pushwoosh 将从 GeoIP 收到的位置保存为特定设备的 City 标签值。 在某些情况下，GeoIP 提交的位置与城市名称不同——例如，当它指的是城市的某个区域或其他行政单位时。在使用默认的 City 标签进行分群时请务必小心：确保选择正确的值。 例如，如果您要定位来自慕尼黑的用户，您必须用一系列 City 标签值来覆盖它，包括“Munich”本身（以及所有相应的值，例如 GeoIP 可能返回并保存为标签值的不同拼写变体）和几个附近的区域。