# 导入推送订阅者

如果您正在从其他推送提供商迁移，您可以将现有的推送订阅者基础从 CSV 文件导入到 Pushwoosh。只要应用程序仍使用相同的 APNs 密钥、Firebase 项目或 HMS 凭据，令牌就会继续工作。用户无需重新安装应用程序或再次授予权限。

此导入操作会注册带有推送令牌的设备。它不会创建细分。导入的设备会获得一个 **CSV import** 标签，您之后可以用它来构建一个细分。要将已注册的 User ID 或 Hardware ID 列表导入到细分中，请参阅[导入细分](/zh/product/audience-data-and-segmentation/segmentation/create-segments/by-import/)。

## 支持的平台

Pushwoosh 仅导入下面列出的平台的推送令牌。

`device_type` 列接受两种不同的格式，具体取决于您的文件来源：

- 一个数字，如果您的导出文件使用 OneSignal 自己的平台代码。
- 一个单词，如果是 Amazon Pinpoint 导出的文件或您手动创建的文件。

不要在同一个文件中混合使用这两种格式，因为相同的数字在每个系统中代表不同的平台。从非 OneSignal 源粘贴数字可能会在错误的平台下静默导入设备。

| 平台 | OneSignal `device_type` 编号 | 可接受的平台名称 |
| :--- | :--- | :--- |
| iOS | `0` | `ios`, `apns`, `apns_sandbox`, `apns_voip` |
| Android | `1` | `android`, `gcm`, `fcm` |
| Amazon | `2` | `amazon`, `adm`, `fireos` |
| Windows | `6` | `windows`, `wns` |
| macOS | `9` | `macos`, `osx` |
| Huawei (HMS) | `13` | `huawei`, `hms` |

包含任何其他值的行都将被跳过（请参阅[为什么某一行会被跳过](#why-a-row-gets-skipped)），包括：

- OneSignal 自己的网页推送、电子邮件和短信设备类型。
- Pushwoosh 不支持的平台，例如已停用的 Windows Phone 或百度推送。

网页推送订阅无法从任何提供商转移。这些用户需要通过您网站上的 Pushwoosh SDK 重新订阅。

## 准备 CSV 文件

您的 CSV 文件必须小于 100 MB。请完全按照下文所示命名列。字母大小写不敏感。您无法在 UI 中映射列，因此请重命名任何不匹配的表头：

| 表头 | 映射到 |
| :--- | :--- |
| `identifier` | 推送令牌（必需） |
| `device_type` | 平台（必需） |
| `external_id` 或 `external_user_id` | User ID |
| `language` | 设备语言 |
| `tags` | 自定义标签值的 JSON 对象 |
| `invalid_identifier` | OneSignal 的“取消订阅”标志。此处标记的行将被跳过 |

如果存在时区列，则不会导入，因为其格式在不同导出版本之间有所不同。

### CSV 示例

这是一个 `subscribers.csv` 示例，包含两台设备，一台使用平台名称，另一台使用 OneSignal 数字代码：

| identifier | device_type | external_id | language | tags |
| :--- | :--- | :--- | :--- | :--- |
| `ios-token-0001` | `ios` | `user-1001` | `en` | `{"plan":"pro"}` |
| `android-token-0002` | `1` | `user-1002` | `en` | `{"plan":"free"}` |

`subscribers.csv` 的纯文本格式表示：

```txt
identifier,device_type,external_id,language,tags
ios-token-0001,ios,user-1001,en,"{""plan"":""pro""}"
android-token-0002,1,user-1002,en,"{""plan"":""free""}"
```

<Aside type="note">
`tags` 值是一个内含引号的 JSON 对象。如果您在 Excel 或 Google Sheets 中构建文件，它们会为您自动给单元格加上引号。如果您在纯文本编辑器中编辑文件，请将整个值用引号括起来，并将其中的每个引号写成两个引号（`"` 变为 `""`），如上面的示例所示。
</Aside>

## 如何导入

1. 前往 **Audience** → **Import CSV** 并选择 **Import push subscribers** 卡片。

   <img src="/push-notifications-import-push-subscribers-1.webp" alt="导入 CSV 屏幕，包含更新标签值、导入推送订阅者和导入事件卡片。"/>

2. 选择您的 CSV 文件。

   <Aside type="caution">
   选择文件时，Pushwoosh 会检查整个文件。如果某一行的引号未闭合，文件会立即被拒绝。与其他 CSV 导入不同，此处允许列数不匹配。提示消息会指出该行及原因，例如“Row 3: a quote mark isn't closed properly.”。这种情况下不会导入任何内容。请修复该行并重新选择文件。
   </Aside>

   <img src="/push-notifications-import-push-subscribers-malformed-toast.webp" alt="标题为 The file cannot be imported 的提示消息，显示 Row 3: a quote mark isn't closed properly. Nothing was imported."/>

3. 查看摘要：
   - 文件中的总行数，以及可导入的行数（按平台细分）。
   - 跳过的行数（按原因细分），并提供一个链接以下载跳过的行（作为 CSV 文件，包含原始列和 `skip_reason` 列）。
   - 在 `tags` 列中检测到的自定义标签，以及 Pushwoosh 为每个标签推断的类型（`string`、`integer`、`boolean` 或 `date`）。如果您的账户中已存在同名但类型不同的标签，它将被标记为冲突。您可以更改类型或在此次导入中跳过该标签。

   <img src="/push-notifications-import-push-subscribers-2.webp" alt="映射步骤摘要，显示按平台导入的行和按原因细分的跳过行。"/>

4. 点击 **Start import**。

导入完成后，请检查各项计数：

* **Devices created：** 新设备。
* **Devices updated：** 已存在的设备。
* **Skipped rows：** 在 Map 步骤（第 3 步）中被排除的行，按原因细分，并提供下载链接。

<img src="/push-notifications-import-push-subscribers-3.webp" alt="导入完成屏幕，显示 Devices created、Devices updated 以及按原因细分并带有下载链接的跳过行。"/>

<Aside type="note">
较早的导入显示单个 **Devices imported** 计数，而不是 **Devices created** 和 **Devices updated**。
</Aside>

<span id="why-a-row-gets-skipped" />

### 为什么某一行会被跳过

以下是“映射”摘要和跳过行 CSV 文件中显示的跳过原因。

| 原因 | 起因 |
| :--- | :--- |
| 网页订阅 | 绑定到其他提供商的密钥。无法转移 |
| 无效令牌 | 已被 APNs / FCM 拒绝（OneSignal 的 `invalid_identifier` 标志） |
| 电子邮件地址 | 请改用[导入联系人](/zh/product/first-steps/start-with-your-project/register-users/import-contacts/) |
| 电话号码 | 请改用[导入联系人](/zh/product/first-steps/start-with-your-project/register-users/import-contacts/) |
| 重复令牌 | 同一个推送令牌在文件中出现多次。第一行生效，后续行将被跳过 |
| 不支持的平台 | 平台不是 Pushwoosh 支持的平台（例如 Windows Phone、百度） |
| 未知平台 | 平台值完全无法识别 |
| 推送令牌为空 | 推送令牌列中没有值 |

## 重新导入相同文件

Pushwoosh 根据每个导入设备的推送令牌生成其 Hardware ID (HWID)，并且相同的令牌总是会生成相同的 HWID。因此，再次导入相同的文件会更新这些现有设备，而不会创建重复项。在修复映射问题后重新运行导入，或定期从新的导出文件中重新同步标签值是安全的。

## 导入之后

导入的设备会带有 **CSV import** 标签，其值为导入的日期和时间。该标签也用于[细分导入](/zh/product/audience-data-and-segmentation/segmentation/create-segments/by-import/)。您可以用它从导入的设备构建一个细分，或在[用户浏览器](/zh/product/audience-data-and-segmentation/user-explorer/)中单独查找它们。