> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/advocate-program/getting-started-with-advocate/import-your-referral-program-data.md).

# 导入你的推荐项目数据

从其他推荐平台切换到 Advocate，您做的不只是导入数据——更是在借助强大的跟踪功能、可自定义的体验和专业支持，提升您项目的潜力。本文将为您介绍：

* 迁移为何重要
* 战略性迁移计划应包含哪些内容
* 可导入哪些数据
* 如何准备文件
* 常见验证错误及避免方法

#### 为何要制定战略性迁移计划？

迁移推荐计划不仅仅是一项技术任务，更是提升客户互动和奖励方式的契机。周密的迁移计划有助于：

* 最大限度减少对推荐体验的影响
* 保留历史数据并确保奖励衔接顺畅 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media)
* 顺利告别旧系统
* 以清晰、令人振奋的方式重新推出推荐计划

![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) 推荐数据和奖励数据的迁移，取决于您能否从当前系统导出数据。您的 Advocate 团队会根据您提供的导出数据，告知您哪些内容可以迁移。

您的 Advocate 团队将与您一起检查导出文件、确认可行的迁移内容，并制定符合项目需求和目标的计划。

#### 您需要完成的事项

* 导出项目的 *用户数据*, *推荐数据*和 *奖励数据*。您可以联系旧推荐平台的客户成功经理（CSM）寻求帮助，也可以使用平台提供的导出工具。
* 将 3 份数据报告分别下载为 CSV 文件，例如： `user_data.CSV`, `referral_data.CSV`和 `reward_data.CSV`.
  * 请参阅下方示例，了解各个 .csv 文件可能包含的内容；也可以查看完整的目标字段参考。

其中包括电子邮件地址、推荐码、分享链接 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media)和自定义字段。请筛除联盟营销人员，以避免重复发放奖励。

![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) 具体取决于分享链接的格式以及是否使用自定义子域名。

用户数据文件包含项目中每位参与者的详细信息。请导出所有参与者的列表，以便及时更新其分享链接和推荐码。

以下字段为 **必填**:

* 用户 ID
* 账户 ID

请使用用户的电子邮件地址作为其 *用户 ID* 和 *账户 ID*。日期应采用 [自 Unix 纪元以来的毫秒数](https://currentmillis.com/)格式。下载 [必填字段示例](https://res.cloudinary.com/product-enablement/raw/upload/v1750169976/CSVs/Migration_User_Import_examples_-_User_Data.csv) ，或使用下方的示例并按 `.csv` 格式保存。

```programlisting
id,accountId,email,firstName,lastName,dateCreated,locale,countryCode,segments
User1@example.com,User1@example.com,User1@example.com,First,Last,1741051242000,en_US,US,
User2@example.com,User2@example.com,User2@example.com,First,Last,,,,"vip,newuser"
User3@example.com,User3@example.com,User3@example.com,First,Last,,en_CA,,
User4@example.com,User4@example.com,User4@example.com,First,Last,,,,newuser
```

其中包括开始日期和转化日期，以及推荐人/被推荐人关系。它支持映射历史推荐成效。

推荐数据文件记录了您的推荐计划中每条推荐关系的状态。

以下字段为 **必填**:

* 推荐人用户 ID
* 推荐人账户 ID
* 被推荐人用户 ID
* 被推荐人账户 ID

请使用用户的电子邮件地址作为其 *用户 ID* 和 *账户 ID*。日期应采用 [自 Unix 纪元以来的毫秒数](https://currentmillis.com/)格式。下载 [必填字段示例](https://res.cloudinary.com/product-enablement/raw/upload/v1750249453/CSVs/Migration_User_Import_examples_-_Referral_Data_-_Referral_Data.csv) ，或使用下方的示例并按 `.csv` 格式保存。

```programlisting
referrerUser,referrerAccount,referredUser,referredAccount,dateReferralStarted,dateConverted,programId
User2@example.com,User2@example.com,User12@example.com,User12@example.com,1740824979000,1740824979000,33435
User1@example.com,User1@example.com,User13@example.com,User13@example.com,1741051242000,1741051242000,33435
User1@example.com,User1@example.com,User17@example.com,User17@example.com,,,33435
User1@example.com,User1@example.com,User18@example.com,User18@example.com,,,33435
```

其中包括金额、发放/兑换日期、奖励类型和状态。这有助于维护用户的信任与公平性。

奖励数据文件记录参与者的奖励历史，包括通过您的推荐计划产生的奖励价值和已兑换金额。

以下字段为 **必填**:

* 推荐人用户 ID
* 推荐人账户 ID
* 奖励名称
* 奖励单位
* 奖励价值
* 创建日期
* 发放日期
* 兑换日期
* 已兑换金额

使用用户的电子邮件地址作为其 *用户 ID* 和 *账户 ID*。日期应采用以下格式： [自 Unix 纪元起经过的毫秒数](https://currentmillis.com/).

奖励价值是奖励以其最小计量单位表示的数值（例如，1.00 美元现金奖励的价值为 100 美分）。如果奖励单位为现金，则应按以下格式包含货币代码： `<unitName>/<Currency>` （例如：Cash/USD）。

{% hint style="warning" %}
**重要提示**：如果 *兑换日期* 和 *已兑换金额* 字段未正确设置——即留空或包含错误值（例如未来日期或不准确的已兑换金额）——用户可能会再次获得兑换该奖励的资格。
{% endhint %}

下载 [必填字段示例](https://res.cloudinary.com/product-enablement/raw/upload/v1750249453/CSVs/Migration_User_Import_examples_-_Reward_Data_-_Reward_Data.csv) ，或使用下面的 `.csv` 格式示例。

```programlisting
User ID,Acccount ID,Referred User ID,Referred Account ID,Reward Name,Reward Unit,Reward Value,Redeemed Amount,Date Created,Date Given,Date Redeemed
User1@example.com,User1@example.com,User2@example.com,User2@example.com,Dollars,CASH/USD,1000,1000,1709712158000,1709712158000,1709712158000
User1@example.com,User1@example.com,User3@example.com,User3@example.com,Points,POINT,100,100,1726164909682,1726164909682,1726164909682
User1@example.com,User1@example.com,User4@example.com,User4@example.com,Points,POINT,100,100,1726164887075,1726164887075,1726164887075
User1@example.com,User1@example.com,User5@example.com,User5@example.com,Points,POINT,100,100,1726164875888,1726164875888,1726164875888
User1@example.com,User1@example.com,User6@example.com,User6@example.com,Points,POINT,10,10,1726164828986,1726164828986,1726164828986
User1@example.com,User1@example.com,User7@example.com,User7@example.com,Account Credit,USD,8000,8000,1726164289997,1726164289997,1726164289997
User1@example.com,User1@example.com,,,Gift Card,USD,10000,10000,1726163864871,1726163864871,1726163864871
User1@example.com,User1@example.com,,,Points,POINT,800,800,1726095906392,1726095906392,1726095906392
User1@example.com,User1@example.com,,,礼品卡,USD,30000,30000,1726163769157,1726163769157,1726163769157
User1@example.com,User1@example.com,,,立减 20,%,20,20,1726180309034,1726180309034,1726180309034
```

{% hint style="warning" %}
**重要提示：** 全部 3 个导出文件都应仅包含来自一个计划的数据。如果文件中包含多个计划的数据，导入时会将其合并到一个计划中。
{% endhint %}

<details>

<summary>迁移计划示例</summary>

每次迁移都有其独特之处，但成功的迁移通常遵循相似的结构，在准备、沟通和执行之间取得平衡。下面的迁移计划旨在确保业务连续性，并为团队和推荐者提供无缝体验。具体时间安排和阶段可根据计划配置灵活调整。

**阶段 1：规划与准备（1–2 周）**

这是奠定基础的阶段，为顺利过渡做好准备。

|    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目标 | <p>• 协调各利益相关方。</p><p>• 完成技术设置。</p><p>• 确认迁移范围。</p><p>• 规划用户沟通。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 任务 | <p>• 获取一份历史数据样本（用户、推荐、奖励），并分享给 Advocate 团队进行审核和字段映射 <img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media" alt="">.</p><p>• 样本通过验证后，导出完整数据集。导出的数据很可能需要进行处理（例如调整表头、字段名称或文件结构），以符合导入要求。</p><p>• 确定上线日期和回滚时间窗口。</p><p>• 以隐藏模式添加 Advocate 小组件（测试环境或未关联的小页面）。</p><p>• 设置必要的集成（例如 Shopify、HubSpot、Segment）。</p><p>• 在 Advocate 中完成计划配置（例如奖励设置、计划规则、电子邮件模板和用户细分）。</p><p>• 端到端测试计划功能——上线前，在测试环境中确认分享、转化和奖励均能正确追踪。</p><p>• 起草面向推荐者的迁移通知。</p><p><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media" alt=""> 推荐关系和奖励的迁移取决于您能否从当前系统导出数据。Advocate 团队可以根据您提供的导出数据告知您哪些内容可行。</p> |
| 提示 | <p>• 如果两个平台同时运行，请确保只有一个平台发放奖励。</p><p>• 找出可能需要特殊处理的高活跃用户（VIP、网红）。</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

**阶段 2：切换与上线（1–2 天）**

这是过渡的关键时刻。请为系统切换期间短暂暂停追踪做好安排，并尽可能选择流量较低的时段进行。

|    |                                                                                                                                                                                                            |
| -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目标 | <p>• 从旧平台平稳切换到 Advocate。</p><p>• 确保用户能够立即使用全新的体验。</p><p>• 避免推荐数据或奖励丢失。</p>                                                                                                                                 |
| 任务 | <p>• 从网站中移除旧平台的脚本/小组件。</p><p>• 正式启用 Advocate 小组件。</p><p>• 导入最终的用户、推荐和奖励数据。</p><p>• 手动追踪/标记系统关闭至新系统上线期间发生的转化。</p><p>• 在 Advocate 控制面板中监控活动情况。</p><p>• 向推荐者发送上线通知。告知用户其推荐链接已更新，最好直接在邮件中附上新链接，方便他们立即开始分享。</p> |
| 提示 | <p>• 如有必要，设置一段简短的奖励暂停缓冲期（例如：“5 月 15 日产生的推荐将在上线后审核并添加。”）。</p><p>• 通过面向推荐者的沟通营造期待感（例如：“您的推荐体验已升级！”）。</p>                                                                                                     |

**阶段 3：迁移后与收尾（1–2 天）**

现在您已正式上线，请确保计划按预期运行，并处理所有遗留事项。

|    |                                                                                                                                                           |
| -- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目标 | <p>• 验证数据完整性和奖励追踪情况。</p><p>• 补录遗漏的转化。</p><p>• 为用户提供支持和指导。</p>                                                                                             |
| 任务 | <p>• 验证推荐人/被推荐人关系在正式环境中运行正常。</p><p>• 导入切换期间发生的所有遗漏转化。</p><p>• 进行质量检查测试（自行发起推荐，确认追踪和奖励逻辑正常）。</p><p>• 提供内部和外部常见问题解答或帮助文档。</p><p>• 监控支持邮箱，排查与旧系统用户相关的问题。</p> |
| 提示 | <p>• 如果您要停用旧的奖励资金账户，请给予用户一段宽限期来兑换奖励。</p><p>• 通过电子邮件或应用内提醒，鼓励用户尽早在新计划中开展推荐活动。</p>                                                                          |

</details>

#### 导入程序数据

1. 在左侧导航菜单中，选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage] → Reporting → Imports & Exports**.
2. 在右上角，选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-ec3276f07285180fbb2167a40e148d3e43e8681c%2F05aa88f72076df5a744d4620574f19cc187b7154fe1f3bb73ad7a892b7d23002.svg?alt=media) **导入**.
3. 从可用选项中选择 *导入类型* ：

   | 导入类型     | 说明                                                                                        |
   | -------- | ----------------------------------------------------------------------------------------- |
   | 用户       | 选择此选项可上传新用户或现有用户数据。您也可以选择从其他账户或平台导入此数据。                                                   |
   | 更新用户奖励余额 | 选择此选项可更新并兑换用户奖励余额。                                                                        |
   | 用户事件     | 选择此选项可上传用户事件数据。                                                                           |
   | 删除用户     | <p>如果要从程序中批量删除现有用户，请选择此选项。</p><p>您也可以删除用户处理记录，并选择：</p><p>• 保留空账户</p><p>• 防止已删除的用户再次创建</p> |
   | 奖励历史记录   | 选择此选项可上传所有奖励信息的记录。您也可以选择从其他账户或平台导入此数据。                                                    |
   | 推荐历史记录   | 选择此选项可上传所有推荐关联的记录。您也可以选择从其他账户或平台导入此数据。                                                    |
4. 选择 **选择文件** 或将要导入的文件拖放到此处。
5. 选择 **导入** 以上传数据。
   * 如果要批量删除现有用户，请选择 **批量删除**.

#### 验证错误参考

您可能会遇到 3 种验证错误：

1. **行内错误消息：** 这些错误会显示在预览验证表格中，并将出错的行标记为红色：

   * `INVALID_FIELD` — 例如， *创建日期* 字段未按以下格式填写： [自 Unix 纪元起的毫秒数](https://currentmillis.com/) .
   * `MISSING_FIELD` — 例如，缺少必填字段，例如 *用户 ID* 或 *账户 ID* 。

   <div data-with-frame="true"><figure><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-eb521fbbc452c243d6b3763ebcb90053b4e9e4dc%2Ff969fa535707c24f4913282d07287a546b348f2448bdb4ca2eef0a30c871fbb6.png?alt=media" alt="" width="375"><figcaption></figcaption></figure></div>
2. **错误提示：** 这些错误会以红色警告消息的形式显示，取代预览验证表格：

   * `MISSING_HEADER` — 例如，缺少必填列标题，例如 *账户 ID* 或 *奖励价值* 缺失。
   * `CSV_PARSING` ——例如，CSV 文件包含格式不正确的特殊字符。
   * `FILE_REF_IO` ——例如，文件已损坏，无法读取。

   <div data-with-frame="true"><figure><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FqSd1JDFy8AQDR2aGJdrz%2FScreenshot%202026-05-25%20at%2017.58.06.png?alt=media&amp;token=26f43eaf-904a-4e1f-8b3c-185700af5edc" alt="" width="563"><figcaption></figcaption></figure></div>
3. **列出的错误：** 这些错误会以错误计数列表的形式显示在 *导入和导出* 屏幕的 *报告* 部分中（如果导入类型没有预览验证表）。行错误和文件错误会一起显示：

   <div data-with-frame="true"><figure><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FQuMoDG2ppJmsEdDwdw50%2FUntitled%20design%20(48).png?alt=media&amp;token=b1cbcb03-ffc7-4ad7-bbbd-c54b81ee3638" alt="" width="563"><figcaption></figcaption></figure></div>

#### 支持

迁移过程中无需独自摸索。我们的 Advocate 入门指导团队随时为您提供帮助，包括：

* 字段映射支持
* 数据格式指导
* 奖励迁移策略
* 测试和质量保证

请联系您的 [Advocate 支持团队](mailto:support-advocate@impact.com).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/advocate-program/getting-started-with-advocate/import-your-referral-program-data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
