跳转到主要内容

​
概述

本指南将带您了解将用户数据导入OneSignal的不同方法。无论您是从其他平台迁移还是添加新订阅者，您都可以使用以下方式导入或更新用户及其订阅：
  • SDK — 推荐用于自动添加新用户和推送订阅。
  • CSV导入器 — 最适合批量导入和更新用户。
  • REST API — 非常适合程序化或自动化更新。
  • 手动输入 — 理想的添加或编辑单个用户的方式。

受众部分内的页面

​
CSV导入

导入或更新电子邮件和电话号码订阅以及其标签、语言、时区、国家、订阅状态（电子邮件/短信）和抑制状态（仅电子邮件）。

CSV导入屏幕

​
准备您的CSV

确保您的文件符合以下标准：
  • UTF-8编码（不带BOM）
  • 没有不可打印字符
  • 清晰、唯一的列标题
  • 文件大小低于150MB
在VS Code或Sublime等纯文本编辑器中打开您的文件。使用UTF-8编码重新打开并验证字符是否正确显示。
您的文件必须包含以下之一：
  • external_id — 推荐。在所有订阅中识别用户。
  • email — 电子邮件订阅所必需。
  • phone_number — 短信订阅所必需。
  • subscription_id — 仅建议在向现有订阅添加外部ID时使用。
subscription_id可以用作传统情况的标识符，或者您的后端跟踪这个唯一的订阅ID的地方。不建议用作添加或更新属性的标识符。
每行只允许一个每种类型的标识符。要将多个电子邮件或号码与同一用户关联，请使用共享相同external_id的单独行。
  • 包含external_id有助于去重用户，支持跨渠道更新，并启用未来的导入。
  • 确保external_id对每个用户都是唯一的，并且是通过SDK login方法设置的相同ID。否则，当用户打开应用时会重置。

​
可用的CSV列

​
external_id
Any unique alphanumeric value
有关更多信息，请参阅外部ID。
​
email
Valid email addresses
创建电子邮件订阅。如果已存在则去重。
​
phone_number
Valid phone numbers
使用E.164格式，如+15555551234。创建短信订阅。
​
subscription_id
UUID v4 assigned by OneSignal
仅用于传统用途。在跟踪OneSignal订阅ID时使用。
​
subscribed
`yes`, `no`
为email、phone_number和subscription_id设置订阅状态。
​
suppressed
`true`, `false`
false从抑制列表中移除电子邮件。
​
timezone_id
IANA TZ formatted time zones
See IANA TZ.
​
country
2-character ISO 3166-2 codes
See ISO 3166-2.
​
language
2-character ISO 639-1 codes
See ISO 639-1.
​
data tags
Alphanumeric values
最多1,000个标签。使用列标题作为键。请参阅标签。

​
从单列导入标签

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

​
访问 CSV 导入器

  1. 转到受众 > 导入
  2. 点击启动 CSV 导入器
  3. 上传您的 CSV（拖放或使用文件选择器）

​
映射字段

上传后：
  • OneSignal 自动将标头映射到已知属性。
  • 确认前请检查映射。

​
更新属性

使用 external_id、email、phone_number 或 subscription_id 来识别您正在更新的用户。 要向现有用户添加新的电子邮件或电话号码，您必须使用 external_id。不要使用 subscription_id — 它不会链接或合并订阅。

​
处理警告

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

显示格式不正确电话号码的错误消息

​
审核

在审核屏幕上：
  • 可选择性地为此导入创建分段
  • 可选择性地删除具有空值的标签：
external_id,tag1,tag2
2349-wefh-h34a,,"tag 2 value"
创建分段可以快速轻松地立即向这些用户发送消息。但是，如果您的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年底提供。
仍然有问题？请联系 support@onesignal.com 并分享您上传的CSV文件以及确认电子邮件的屏幕截图。我们很乐意查看！

​
CSV 导入历史

您可以在受众 > 导入 > CSV > 查看以前的导入中查看导入历史（请注意，使用我们以前的单通道 CSV 导入流程进行的任何导入都不会包含在此列表中）。

​
REST API

通过我们的 REST API 导入和更新用户和订阅：

创建用户

推荐。可用于创建和/或更新用户和订阅。

按别名创建订阅

仅用于向用户添加订阅。

​
手动输入

  • 手动添加电子邮件
  • 手动添加电话号码
导航至受众 > 订阅 > 更新/导入用户旁边的箭头 > 手动添加电子邮件以打开新的模态框，您可以在其中添加个别用户的电子邮件和您希望与该用户关联的任何数据标签。

按钮下拉菜单显示高亮显示的手动添加电子邮件选项