通过CSV文件或手动输入，在OneSignal控制面板中批量导入或更新用户。常见用例包括从另一个平台迁移用户、更新用户详细信息，以及使用标签和分段组织用户。
CSV导入
使用CSV文件导入或更新电子邮件地址、电话号码、外部ID、标签、语言、时区、国家等。
CSV要求
确保您的.csv文件符合以下要求：
- UTF-8编码（不带BOM）
- 没有不可打印字符（没有特殊字符或非ASCII字符）
- 清晰、唯一的列标题
- 文件大小低于150MB（约200万行）
- 至少包含以下标识符之一：
external_id — 推荐。在所有订阅中识别用户。email — 创建新电子邮件订阅所必需。有关更多信息，请参阅邮件地址验证。phone_number — 创建新SMS订阅所必需。subscription_id — 仅建议在您的后端已跟踪订阅ID并希望设置external_id的情况下使用。
每行只允许一个每种类型的标识符。要将多个电子邮件或电话号码与同一用户关联，请使用共享相同external_id的单独行。
- 包含
external_id以去重用户。确保它与SDK login方法中使用的ID匹配——否则当用户打开应用时会重置。
- 要更改订阅状态，行必须包含
email、phone_number或subscription_id。仅external_id是不够的。
subscription_id不会链接或合并订阅。使用external_id向现有用户添加新电子邮件或电话号码。
支持的列
您的用户ID。有关更多信息，请参阅外部ID。应该是通过SDK login方法使用的相同ID。 用户的电子邮件地址。创建电子邮件订阅。如果应用中已存在则去重。 用户的电话号码，使用E.164格式，如+15555551234。创建SMS订阅。如果应用中已存在则去重。 subscription_id
String (UUID v4 assigned by OneSignal)
仅建议在您的后端已跟踪OneSignal订阅ID的情况下使用。 设置订阅状态。行必须包含email、phone_number或subscription_id——不能仅使用external_id。
suppressed
Boolean ('true', 'false')
与email一起使用以添加或从抑制列表中移除。
true将电子邮件添加到抑制列表。false从抑制列表中移除电子邮件。
timezone_id
String (IANA TZ formatted time zones)
country
String (2-character ISO 3166-2 codes)
每次导入最多包含1,000个标签。在列标题中使用标签键，在行中使用标签值。您也可以使用单个tags列搭配JSON格式——详见批量标签更新。 标签限制和限制条件
标签计划限制按用户计算，而不是按应用计算。例如，如果您的计划每个用户允许20个标签，而用户已有19个，则只能再添加1个——即使应用本身可以有无限数量的标签键。
- 使用批量标签更新工作流程导出用户、清除不需要的标签值，并在启用删除选项的情况下重新导入。
- 避免在标签键中使用空格——请改用下划线。
保留和受限的标签键
以下标签键已被保留，不应使用：
- “user”
- “subscription”
- “message”
- “template”
- “app”
- “org”
- “custom_data”
- “dynamic_content”
如果您意外将其中一个设置为标签键，请通过更新用户API将其删除。
标签覆盖和删除
在CSV导入期间：
- CSV中包含的标签将被提供的值覆盖。
- CSV中未包含的标签在用户记录中保持不变。
如果导入后标签仍然存在，请验证：
- 标题列包含标签键。
- 行不包含任何值。
- 您在审核屏幕中选择了”删除具有空值的标签”选项。
被其他来源添加的标签
如果删除的标签在导入后重新出现，可能是某个集成正在自动写回它们。常见来源包括：
- Segment
- HubSpot
- Journeys
- SDK标记方法
- 自定义API或ETL管道
检查集成映射和事件触发器，确保它们不会覆盖您的CSV更改。
从单个列导入标签
您可以设置单个tags标头，每个用户行包含引号内所有键值对的JSON映射，而不是为每个标签键使用单独的列标头。如果您以前导出了带有标签的CSV并希望重新导入而无需重新格式化，这特别有用。
标签必须格式化为JSON对象，每个键值对周围用2组双引号括起来。
userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
level:30和color:teal。
示例：批量删除标签
要批量删除标签，请导出当前数据，清空标签值，然后启用删除选项重新导入CSV。
导出您的数据
- 在OneSignal控制台中，导航到受众 > 订阅。仅启用外部ID、订阅ID和标签列（以及可选的电子邮件或电话号码）。
- 点击导出以导出CSV。
清除要删除的标签值
在文本编辑器中打开导出的CSV，将每个要删除的标签值设置为空字符串。例如，编辑前包含标签值的行：userA,example@email.com,"{""level"":""30"",""color"":""teal""}"
userA,example@email.com,"{""level"":"""",""color"":""""}"
level和color。 使用删除选项重新导入CSV
- 获取编辑后的CSV并导入。
- 在审核屏幕上，为删除空值标签选择是。OneSignal在导入期间删除空值的标签。
要仅删除特定标签，请清除这些标签的值，并保持其他标签不变。启用删除选项时，仅删除空值。
需要帮助？
- 尝试上面的在导入前使用AI检查您的CSV部分。
- 联系
support@onesignal.com并分享您上传的CSV文件以及确认电子邮件的屏幕截图。我们很乐意查看！
邮件地址验证
邮件地址验证在邮件到达您的受众之前检测邮件地址中的常见问题。它标记可能增加退信率或损害发送者声誉的拼写错误、无效域名、基于角色的地址和一次性邮件服务。
邮件地址验证
在 CSV 导入期间和批量验证邮件地址，以减少退信并保护您的发送者声誉。
在导入前使用AI检查您的CSV
如果您的CSV格式存在错误或疑问，您可以向AI工具（如Claude、ChatGPT或类似工具）描述您的CSV问题，以便在再次导入之前自动清理或重建您的文件。
在导入数千条记录之前，始终使用小样本（5-10行）进行测试。
删除标签
标签格式
识别无效格式
修复电话号码
从其他平台迁移
我想从这个CSV中删除除"user_name"之外的所有标签。
请：
1. 仅保留"user_name"标签列。
2. 删除所有其他标签列。
3. 格式化CSV使其符合此文档中的OneSignal导入要求：
https://documentation.onesignal.com/docs/en/import
这是我的CSV：
[粘贴CSV]
我有多个标签列，如tag_first_name、tag_last_name和tag_city。
根据OneSignal导入文档，每个标签必须：
- 使用tag_前缀
- 仅包含字母数字字符和下划线
- 遵循支持的数据类型
您能查看我的CSV，识别格式不正确的内容，并返回符合这些要求的修正版本吗？
文档链接：
https://documentation.onesignal.com/docs/en/import
OneSignal在导入期间拒绝了我的CSV。
请：
1. 验证我的CSV结构。
2. 识别任何格式问题（标题、ID列、标签格式、引用）。
3. 返回遵循此文档要求的修正版本：
https://documentation.onesignal.com/docs/en/import#prepare-your-csv
这是文件：
[粘贴CSV]
我的导入失败，因为电话号码不是E.164格式。
请：
1. 将所有电话号码转换为E.164格式。
2. 保持所有其他字段不变。
3. 确保CSV符合OneSignal的所需结构：
https://documentation.onesignal.com/docs/en/import
当前格式示例：(555) 555-1234
这是我的CSV：
[粘贴CSV]
我正在从[平台名称]迁移到OneSignal。
您能将此CSV转换为符合OneSignal的导入格式吗？
包括：
- `external_id`
- 任何使用`tag_`前缀转换的标签（如果需要）
- E.164格式的电话号码（如果适用）
参考文档：
https://documentation.onesignal.com/docs/en/import
这是我的CSV：
[粘贴CSV]
导入步骤
导航至受众 > 导入并点击启动CSV导入器。
映射字段
OneSignal自动将CSV标头映射到已知属性。在确认之前查看映射 — 使用external_id、email、phone_number和/或subscription_id作为标识符，而非标签。要向现有用户添加新的电子邮件或电话号码，您必须使用external_id。不要使用subscription_id — 它不会链接或合并订阅。
检查并确认
审核屏幕允许您：
- 自动创建分段 — 在每个导入的用户上添加标签并创建匹配的分段。注意您的计划限制。
- 删除具有空值的标签 — 删除CSV中值为空白的任何标签。这有助于清除不需要的标签并保持在计划限制内。
- 配置邮件地址验证 — 配置邮件地址验证设置以减少退信并保护您的发送者声誉。
例如，给定以下CSV：external_id,tag1,tag2
UserA,,"tag2value"
UserB,"tag1value",
tag1将从UserA中删除，tag2将从UserB中删除。点击确认并导入。状态屏幕显示进度。 导入已开始。当导入完成时，您将收到来自contact@onesignal.com的确认邮件。
电子邮件确认
导入完成后，您将收到来自contact@onesignal.com的确认电子邮件，其中包含以下数据。请注意，单个用户可以拥有多个订阅（例如，电子邮件 + 推送），因此订阅计数可能高于您的行数。
已添加的订阅记录 — 创建的新电子邮件或短信订阅。0 表示未找到唯一的 email 或 phone_number 标识符。
已修改的订阅记录 — 数据发生更改的订阅（标签、属性等）。例如，10 个外部 ID，每个关联 20 个订阅 = 修改了 200 条记录。
跳过的订阅更新 — 因所述原因跳过的订阅。如果原因是”超过您应用的标签限制”，请删除标签并重新导入或升级您的计划。
未导入 — 未更新或导入的行。常见原因：external_id 与任何现有订阅不匹配，或 email/phone_number 已存在且没有新数据可设置。
创建的新分段 — 分段名称（如果您选择了该选项）。
在以上示例中：
- 从唯一电子邮件地址或电话号码创建了
100 个订阅（这些地址或号码之前不在应用中）。
- 更新了
37,814 个订阅（不是用户数量——每个用户可以有多个订阅）。
621,852 行未导入，因为其外部 ID 与现有用户不匹配，或电子邮件/电话号码已存在且没有新数据。
分段仅计算已订阅的订阅。未订阅的订阅通过导入更新，但不会反映在分段计数中。分段改进正在进行中。 手动输入
您可以通过OneSignal控制面板手动添加用户的电子邮件和电话号码订阅，方法是导航到受众 > 用户 > 更新/导入用户 > 手动添加用户。
在新用户屏幕上，包含您想要的数据并选择创建用户。
常见问题
CSV导入需要多长时间？
持续时间取决于文件大小。大多数导入在几分钟内完成。导入完成后，您将收到来自contact@onesignal.com的电子邮件——将该地址添加到您的联系人以确保送达。
可以撤销CSV导入吗？
不可以。CSV导入没有内置的撤销功能。如果您需要撤销更改，请准备一个包含正确值的新CSV并重新导入。对于标签删除，请使用批量标签更新工作流程。
为什么我的段计数与CSV中的行数不匹配？
段仅计算已订阅的订阅数量。取消订阅的订阅通过导入更新，但不会反映在段计数中。
为什么我的导入对某些行显示”未导入”？
当external_id与应用中的任何现有订阅不匹配，或者当email或phone_number已经存在且没有新数据可设置时，行会被跳过。查看电子邮件确认部分了解每个状态的详细信息。
为什么删除的标签一直回来？
导入后，集成或SDK调用可能会重新添加标签。常见来源包括Segment、HubSpot、Journeys、SDK标签方法和自定义API。查看您的集成映射和事件触发器。 
