电信行业入门：用户数据与分群

本指南将指导您在 Pushwoosh 中设置电信订户个人资料，并将其转化为有效的分群：套餐包到期提醒、低余额警报、充值确认和漫游欢迎消息。请完成每个部分，您构建的第一个分群将返回一个非零的受众，这样您就无需联系支持团队。

最常见的一个错误是标签类型。存储在 Integer 标签中的日期在标签列表中看起来没有问题，但会悄无声息地导致每个日期分群都返回零用户。请先选择类型，然后再加载数据。

先决条件

• 您的 Pushwoosh 帐户中有一个应用程序，并已集成 SDK 或通过 API 注册了设备。
• 一个具有设置标签权限的 API 访问令牌。
• 需要开发人员协助完成服务器到服务器的更新任务。
• 一个您可以映射到 Pushwoosh 的订户标识符：可以是 User ID（通常是 MSISDN，即国际格式的订户电话号码，或内部订户 ID），也可以是设备 HWID。

电信订户个人资料是什么样的

下表列出了涵盖标准电信场景的标签。请在首次加载数据前创建它们，并确保类型完全一致。

标签	类型	示例值	用途
msisdn	String	923001234567	身份识别和 SMS 定向
tariff_plan	String	Gold Postpaid	特定套餐优惠
prepaid_postpaid	String	prepaid	按计费模式划分用户群
balance	Integer	50	低余额警报
bundle_id	String	DATA_5GB_30D	提醒涉及哪个套餐包
bundle_expiry_date	Date	2026-09-20 21:00:00	套餐包到期提醒
roaming_status	Boolean	true	漫游欢迎消息和漫游费用警告

表中的两行决定了这些场景是否能正常工作。

• bundle_expiry_date 必须是 Date 类型的标签。只有 Date 类型的标签才能使用相对运算符，例如 在未来 N 天至 M 天之间，这样可以表达“套餐包将在三天后到期”，而无需每晚重新计算分群。
• bundle_id 与到期日期分开。一个标签存储日期，另一个标签存储它所属的套餐包。将两者存储在一个标签中需要在分群内部解析字符串，而分群构建器无法做到这一点。

为什么要在首次上传前决定标签类型

标签在首次接收到值时会自动创建，其类型是根据第一个值推断出来的。整数会变为 Integer，带小数点的数字会变为 Price，字符串会变为 String（如果匹配公认的日期时间格式，如 2024-10-02 22:11，则会变为 Date），数组会变为 List，true/false 会变为 Boolean。

对于电信数据，这种推断会失败，因为到期日期通常以 Unix 时间戳的形式发送：

• 您发送 bundle_expiry_date 时使用了数字 1758393600。这是一个整数，所以标签被创建为 Integer 类型。值加载正确，标签看起来也正常，但系统永远不会为它提供日期运算符。
• 该标签已作为 Integer 存在，后来您切换为发送 "2026-09-20"。这个值无法再解析为数字，因此会被丢弃，且不会报告任何错误。API 仍然会返回成功，设备会保留其旧值或根本没有值。

这两种情况最终都会导致分群返回零用户，并且没有任何地方提供错误信息来解释原因。

标签类型一旦创建就无法更改。修复错误的类型意味着需要创建一个具有正确类型的新标签，并将值重新加载到其中。旧标签会一直保留在列表中，直到您删除它。

为防止这两种情况，请自行设置类型：

1. 打开您 Control Panel 的 Tags 页面。
2. 点击 创建标签。
3. 输入标签名称并从列表中选择其类型。在首次上传前，对上表中的每个标签重复此操作。
4. 在 bulkSetTags 中，发送 create_missing_tags: false。这样，如果标签缺失，API 将返回错误，而不是使用猜测的类型创建它。

如何通过服务器到服务器方式更新个人资料

电信个人资料数据每天都在变化，因此它通常作为批处理任务加载，而不是通过移动 SDK 加载。

1. 在您这边构建每日增量数据：自上次运行以来余额、套餐包或漫游状态发生变化的订户。通常不需要每晚进行全量重载，这会消耗您的请求量。
2. 将批处理数据发送到 bulkSetTags，当 MSISDN 是您的 User ID 时，通过 user_id 定位设备，否则通过 hwid 定位。一个请求可以携带多个设备，该方法期望至少有 50 个设备。对于单个订户，请改用 setTags。
3. 使用 bulkSetTags 状态 轮询返回的 request_id，直到任务完成。请求时带上 ?detailed=true 参数并记录结果，因为任务完成不等于每个值都被接受。
4. 使用相同的有效负载重试失败的批处理。设置标签是幂等的：发送相同的值两次会得到相同的个人资料。

每日套餐包更新

{
  "application": "XXXXX-XXXXX",
  "auth": "your API access token",
  "create_missing_tags": false,
  "devices": [{
    "user_id": "923001234567",
    "tags": {
      "bundle_id": "DATA_5GB_30D",
      "bundle_expiry_date": "2026-09-20 21:00:00",
      "balance": 50,
      "roaming_status": false
    }
  }]
}

Date 类型的标签接受哪些日期格式

Date 类型的标签以秒为单位存储 Unix epoch 时间戳。请发送以下格式之一：

• 以秒为单位的 epoch 值，作为数字：1758393600。
• 带分隔符的日期时间字符串：2026-09-20 21:00:00、2026-09-20 21:00 或 2026-09-20。不带时间的日期表示午夜。
• 带偏移量的 ISO 8601 字符串：2026-09-20T21:00:00+05:00。

有两种格式的行为方式可能会让大多数集成感到意外：

• 不带时区的字符串被读取为 UTC 时间。 它不会按您的本地时间读取。一个在卡拉奇时间 21:00 到期的套餐包应为 2026-09-20T21:00:00+05:00，或匹配的 epoch 值。2026-09-20 21:00:00 在实时时间上早了三个小时，这会导致订户在每日提醒的批次之间移动。
• 一串数字是 epoch 值，而不是日期。 "20260920" 不是 2026 年 9 月 20 日，而是一个指向 1970 年的 epoch 时间戳。请发送真实的 epoch 值或带分隔符的字符串。

与任何可接受格式都不匹配的值将被丢弃，而不会导致请求失败。这就是为什么上面的第 3 步要检查任务结果，而不仅仅是 HTTP 状态。

分群配置方法

下面的每种配置方法都对应一个分群。打开 Segments 部分，点击 创建细分客群 打开构建器，然后添加列出的筛选器。有关构建器的完整演练，请参阅按标签创建分群。

套餐包在三天后到期

目标是当前套餐包将在三天内到期的订户，以便在续订仍有意义时发送提醒。

• 标签： bundle_expiry_date
• 运算符： 打开运算符列表，转到 相对日期 部分，然后选择 在未来 N 天至 M 天之间
• 值： 3 和 3

对于最后一天的提醒，将两个值都更改为 1 和 1。当消息需要指明具体套餐包时，添加一个关于 bundle_id 的第二个筛选器。

此处请勿使用“周年纪念”运算符

周年纪念 部分提供了 在 N 天后 运算符。该运算符仅比较日期和月份，因此它会匹配所有在任何年份的该日期套餐包到期的订户。请将其用于生日，而不是套餐包有效期。

低余额

目标是无法再支付下一次续订费用的预付费订户。

• 标签： balance，运算符 小于或等于，值 50
• 标签： prepaid_postpaid，运算符 等于，值 prepaid

两个条件都放在同一组中，并用 且 连接。

进入漫游状态

目标是当前在国外的订户，以便发送包含当地费率的欢迎消息。

• 标签： roaming_status，运算符 是

基于标签的分群反映的是编译时的状态。当您需要消息在漫游开始的瞬间发出时，应通过漫游事件触发 customer journey，而不是向此分群发送消息。

充值确认及其他响应

确认充值是对单个订户行为的响应，而不是一个需要编译的受众。请通过您的计费系统使用 postEvent 发送一个自定义事件，并由此启动一个 customer journey。这同样适用于套餐包购买和套餐变更。

分群返回零用户

请按顺序检查以下各项。前三项涵盖了向支持团队报告的大多数情况。

1. 在 Tags 页面检查标签类型。 如果 bundle_expiry_date 是 Integer，则日期运算符从未被应用，分群比较的是数字。请创建一个 Date 类型的标签并重新加载值。
2. 检查值是否确实已送达。 打开 User Explorer，找到您知道在批处理中的一个订户，并查看他们的标签。如果任务成功后标签为空，则表示值因格式问题被拒绝，最常见的是纯数字字符串或与任何布局都不匹配的日期。
3. 检查运算符部分。 周年纪念 下的 在 N 天后 会忽略年份。而 相对日期 下的 在未来 N 天至 M 天之间 不会。
4. 检查时区。 没有偏移量发送的到期时间戳会被读取为 UTC 时间，这可能会将订户转移到您提醒计划的前一天或后一天。
5. 在读取数量之前重新计算分群，这样您看到的就不是缓存的大小。请参阅计算分群大小。

需要考虑的限制

• 标签类型是永久的。 在首次上传前规划好个人资料，因为之后修复类型意味着需要一个新标签和一次全量重载。
• 相对日期运算符在高速交付分群中不可用。 配置为高速交付的应用程序会预编译其分群，其中不提供相对日期运算符。套餐包到期提醒必须作为普通分群运行。
• 批处理任务不是实时的。 分群看到的是截至上次成功加载时的个人资料。必须在余额变化后几秒内触发的场景应属于事件触发的 journey，而不是夜间批处理。