跳转到主要内容

​
概述

本指南介绍使用CSV或手动输入在OneSignal控制面板中导入或更新用户及其属性。这有助于批量更新，如从另一个平台迁移用户、更新用户详细信息以及创建特定用户列表（使用标签和分段）。 更新用户的选项包括：
  • 创建新的电子邮件和/或电话号码订阅
  • 设置外部ID
  • 更新用户属性，如标签、订阅状态、语言、时区、国家和抑制状态
有关更新或创建用户的其他选项，请参阅：

OneSignal控制面板受众 > 导入

​
CSV导入

使用CSV文件导入电子邮件地址、电话号码、外部ID、标签、语言、时区、国家等！ 通过导航到受众 > 导入并点击启动CSV导入器，在OneSignal控制面板中访问CSV导入器。

导入CSV屏幕

​
CSV要求

确保您的文件符合以下要求：
  • UTF-8编码（不带BOM）
  • 没有不可打印字符（没有特殊字符或非ASCII字符）
  • 清晰、唯一的列标题
  • 文件大小低于150MB（约200万行）
  • 至少包含以下标识符之一：
    • external_id — 推荐。在所有订阅中识别用户。
    • email — 创建新电子邮件订阅所必需。
    • phone_number — 创建新SMS订阅所必需。
    • subscription_id — 仅建议在您的后端跟踪订阅ID并希望设置external_id的情况下使用。**subscription_id不会链接或合并订阅。**这意味着您不能通过subscription_id身份添加电子邮件或电话号码，您必须使用external_id。
每行只允许一个每种类型的标识符。要将多个电子邮件或电话号码与同一用户关联，请使用共享相同external_id的单独行。
  • 包含external_id有助于去重用户
  • 确保external_id对每个用户都是唯一的，并且是通过SDK login方法使用的相同ID。否则，当用户打开应用时它将重置。

​
支持的列

​
external_id
String
您的用户ID。有关更多信息，请参阅外部ID。应该是通过SDK login方法使用的相同ID。
​
email
String
用户的电子邮件地址。创建电子邮件订阅。如果应用中已存在则去重。
​
phone_number
String in E.164 format
用户的电话号码，使用E.164格式，如+15555551234。创建SMS订阅。如果应用中已存在则去重。
​
subscription_id
String (UUID v4 assigned by OneSignal)
仅建议传统用途使用。当您的后端跟踪OneSignal订阅ID时使用。
​
subscribed
Boolean ('yes', 'no')
为email、phone_number和subscription_id设置订阅状态。
​
suppressed
Boolean ('true', 'false')
与email一起使用以添加或从抑制列表中移除。
  • true将电子邮件添加到抑制列表。
  • false从抑制列表中移除电子邮件。
​
timezone_id
String (IANA TZ formatted time zones)
用户的时区，使用IANA TZ格式。
​
country
String (2-character ISO 3166-2 codes)
用户的国家代码，使用ISO 3166-2格式。
​
language
String (ISO 639-1 codes)
用户的语言，使用ISO 639-1格式。
​
tags
String
每次导入最多包含1,000个标签。在列标题中使用标签键，在行中使用标签值。或参见下面的从单个列导入标签。

​
从单个列导入标签

您可以设置单个tags标头，每个用户行包含引号内所有键值对的JSON映射，而不是为每个标签键使用单独的列标头。如果您以前导出了带有标签的CSV并希望重新导入而无需重新格式化，这特别有用。
CSV标头示例
external_id,email,tags
标签必须格式化为JSON对象，每个键值对周围用2组双引号括起来。
CSV行示例
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
导入时，OneSignal自动将每个键值对转换为不同的标签。例如，上述行将转换为2个标签：level:30和color:teal。

​
在导入前使用AI检查您的CSV

如果您的CSV格式存在错误或疑问，您可以向AI工具（如Claude、ChatGPT或类似工具）描述您的CSV问题，以便在再次导入之前自动清理或重建您的文件。
  • 删除标签
  • 标签格式
  • 识别无效格式
  • 电话号码格式
  • 来自其他平台的数据
删除不需要的标签的AI提示示例
我想从这个CSV中删除除"user_name"之外的所有标签。

请：
1. 仅保留"user_name"标签列。
2. 删除所有其他标签列。
3. 格式化CSV使其符合此文档中的OneSignal导入要求：
   https://documentation.onesignal.com/docs/en/import

这是我的CSV：
[粘贴CSV]
在导入数千条记录之前，始终使用小样本（5-10行）进行测试。

​
映射字段

上传后：
  • OneSignal自动将标头映射到已知属性。
  • 确认前请查看映射。
    • 使用external_id、email、phone_number和/或subscription_id作为用户的标识符。很少会将这些用作标签。
要向现有用户添加新的电子邮件或电话号码，您必须使用external_id。不要使用subscription_id — 它不会链接或合并订阅。

导入CSV映射字段屏幕

​
处理警告

如果OneSignal检测到格式问题：
  • 修复CSV并重新上传（推荐）
  • 或取消选中受影响的列以跳过导入

​
审核

在审核屏幕上，您可以选择：
  • 自动为此导入创建分段。
    • 此选项执行2项操作：1. 在每个用户上设置另一个标签，2. 使用此标签创建一个分段。
    • 在此示例中，标签将是list-a，分段将被称为list-a。
    • 请注意您的计划的标签和分段限制。
  • 删除具有空值的标签。
    • 选择”是”将自动删除任何具有空值的标签。
    • 在此示例中，您将从UserA删除tag1，从UserB删除tag2。
    • 这有助于删除标签并保持在您的计划限制内。
external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",

导入CSV审核屏幕

点击确认并导入后，状态屏幕显示进度。导入完成后您将收到一封电子邮件。
您已完成导入过程！
  • 您的导入时长取决于文件大小。
  • 检查您的电子邮件并将contact@onesignal.com添加到您的电子邮件联系人，以确保您收到电子邮件确认。

​
电子邮件确认与故障排除

CSV 上传完成后，您将收到包含以下数据的确认电子邮件：
  • 已添加的订阅记录
    • 通过 CSV 上传创建的新电子邮件和/或短信订阅数量。
    • 0 表示列表不包含用于创建订阅的唯一 email 和/或 phone_number 标识符。
  • 已修改的订阅记录
    • 某些数据发生更改的订阅数量，如设置的标签或其他属性。
    • 请记住，用户可以拥有多个订阅。例如，如果您上传了 10 个外部 ID 的列表，每个都关联了 20 个订阅，您将看到 200 个订阅记录被修改。
  • 跳过的订阅更新
    • 因提供的原因而跳过的订阅数量。
    • 如果您上传了 email 和/或 phone_number 的 CSV，这些订阅很可能已创建。
    • 如果原因是”由于超过您应用的标签限制”，那么您需要删除标签并重新上传。或升级您的计划。
  • 未导入
    • 未获得更新或导入的行数。
    • 通常发生在：
    1. 您在 CSV 中设置的 external_id 在 OneSignal 应用的任何订阅中都不存在
    2. email 和/或 phone_number 订阅在 OneSignal 应用中已存在。
  • 创建的新分段
    • 您创建的分段名称（如适用）。

电子邮件确认示例。

在示例中：
  • 创建了 100 个订阅，因为 email 和/或 phone_number 列包含当前在 OneSignal 应用中不存在的唯一电子邮件地址和/或电话号码。
  • 更新了 37814 个订阅。这不是用户的计数。请记住，用户可以拥有多个订阅。
  • CSV 的 621852 行未导入。要么因为它们没有映射到 OneSignal 应用中用户的外部 ID，要么电子邮件和/或电话号码已存在且没有唯一数据可设置。
目前分段仅计算已订阅订阅的数量。它们不计算取消订阅的订阅，尽管它们的数据已更新。如果您的分段计数与CSV不匹配，那是因为分段目前没有计算取消订阅的订阅。这目前正在处理中。新的和改进的分段功能将在2025年底提供。

​
常见故障排除技巧

以下是我们在CSV导入中看到的常见问题。如果您遇到问题，我们还建议尝试上面的在导入前使用AI检查您的CSV部分。

​
标签限制

  • 您的标签计划限制是按用户计算的。您可以在每个应用中拥有无限数量的标签，但每个用户都受计划限制约束。
  • 示例：您的计划限制是每个用户20个标签。
    • 如果用户已经有19个标签，您只能再向该用户添加1个标签。
    • 您的应用可以有1000种不同的标签组合，但每个用户一次只能有20个。
  • 建议：
    • 使用控制面板CSV导出导出用户的外部ID、标签、电子邮件和/或电话号码。
    • 设置带有要删除的标签的CSV标头，首先导入这些标签。
    • 设置带有要保留的标签的第二个CSV，其次导入这些标签。
    • 有关更多详细信息，请参阅上面的从单个列导入标签部分。

​
标签覆盖和删除

在CSV导入期间：
  • CSV中包含的标签将被提供的值覆盖。
  • CSV中未包含的标签在用户记录上保持不变。
如果导入后标签仍然存在，请验证：
  • 标题列包含标签键。
  • 行不包含值。
  • 您在审核屏幕中选择了”删除具有空值的标签”选项。

​
标签被添加的其他来源

如果删除的标签在导入后重新出现，集成可能会自动将它们写回。常见来源包括：
  • Segment
  • HubSpot
  • Journeys
  • SDK标签方法
  • 自定义API或ETL管道
查看集成映射和事件触发器，以确保它们不会覆盖您的CSV更改。
需要帮助？
  • 尝试上面的在导入前使用AI检查您的CSV部分。
  • 联系support@onesignal.com并分享您上传的CSV文件以及确认电子邮件的屏幕截图。我们很乐意查看！

​
手动输入

您可以通过OneSignal控制面板手动添加用户的电子邮件和电话号码订阅，方法是导航到受众 > 用户 > 更新/导入用户 > 手动添加用户。

手动添加用户屏幕

在新用户屏幕上，包含您想要的数据并选择创建用户。