文件导入与数据源

如果客户数据已经存在于其他系统（CRM、财务软件、电子表格）中，就无需等待他们访问网站：直接上传文件即可。导入用于从 CSV 一次性上传档案，数据源则用于定期从网址文件、S3 或 Google 表格中加载档案和事件。

这两个工具都对“所有者”“管理员”和“经理”开放。

从 CSV 导入档案

在菜单中打开数据 → 档案导入，或点击档案页面顶部的档案导入。

文件要求

• CSV 文件，第一行为列标题。
• 分隔符可以是逗号、分号或制表符，系统会自动识别。
• 文件大小不超过 20 MB。
• 至少包含一个标识符列：您系统中的客户 ID、邮箱或电话。

示例：

email;phone;first_name;city;customer_id;bonus
[email protected];+86 138 0013 8000;Anna;Shanghai;1001;350

如何上传

1. 点击选择 CSV 文件并选择文件。
2. 表格中会显示文件的列、示例值和目标字段。为每一列指定：
   • 身份标识：User ID、邮箱、手机号或匿名 ID：系统据此查找或创建档案。每种类型只能选择一次。
   • 属性：档案的一项特征；在旁边用拉丁字母填写键，例如 city 或 bonus_balance。
   • 跳过：该列不导入。
3. 点击开始导入。

OneTrace.pro 会根据标题自动建议目标：email 对应邮箱，phone 和 mobile 对应手机号，customer_id 和 user_id 对应 User ID。其他标题会转换为属性键（小写字母加下划线），例如 First name、Last name、City 和 Country 会分别变为 first_name、last_name、city 和 country 属性。中文标题无法自动转换为键，请为其手动填写键。开始导入前请检查这些建议。

导入进度

导入在后台进行：页面上会显示进度条、状态和计数“已处理 N/M，错误：K”。您可以关闭页面，导入会继续进行。出错的行会连同行号一起列出。导入完成后，打开档案按钮会跳转到档案列表。

右侧的历史记录模块显示最近 20 次导入：文件、上传者和上传时间、状态（“已上传”“排队中”“处理中”“已完成”“失败”）以及结果。

行的处理方式

• 如果已存在具有相同标识符的档案，该档案会被更新：新属性会被添加，同名属性会被覆盖。如果一行中出现了两个不同档案的标识符，这两个档案会被合并，参见档案。
• 空单元格会被跳过，不会清除已有的值。
• 数字和 true/false 会分别保存为数字和布尔值。
• 文件中的邮箱和电话既会成为档案的标识符，也会成为档案属性。
• 电话号码中的空格、括号和连字符会被去除。请带国家代码填写：+86 138 0013 8000。不带国家代码的号码（例如 138 0013 8000）会以错误的国家代码保存。
• 没有任何有效标识符的行会被跳过并记为错误。

导入会为每一行生成一个 $identify 事件，因此属性变更可能会触发以属性变更为触发器的旅程。如果不希望这样，请在导入期间暂停这些旅程。

数据源

数据源是按计划定期执行的导入。适用于 CRM 或仓库系统每晚生成最新导出文件的场景：OneTrace.pro 会自动获取文件，并更新档案或添加事件。

准备工作

首先在集成板块中创建连接（需要“管理员”或“所有者”角色）：

• 网址文件：通过 HTTP(S) 地址获取的文件。如果文件受保护，请填写授权请求头，例如 Bearer 加令牌。
• S3 中的文件：AWS、Yandex Object Storage、MinIO 及其他兼容存储的存储桶。
• Google 表格：使用 Google 服务账号密钥访问。请将表格以只读权限共享给该账号。

文件格式：CSV、JSON（对象数组，不超过 50 MB）和 JSON Lines。

如何创建数据源

1. 打开数据 → 数据源，点击新建数据源。
2. 填写名称并选择连接。
3. 填写连接设置：文件网址和格式、存储桶中的文件路径，或表格 ID 和范围（例如 Sheet1!A:F）。
4. 点击加载列，OneTrace.pro 会读取前几行。
5. 在导入为字段中选择档案（每一行更新档案属性）或事件（每一行是一个事件）。
6. 选择计划：从每 15 分钟到每天一次。
7. 在列表格中为每一列指定目标，与 CSV 导入相同。
8. 点击保存。

对于事件，列表格中还有事件名称、事件属性和事件时间。时间列为必填项。可以在事件名称字段中为所有行设置统一的事件名称（例如 order_completed），或选择记录事件名称的列。

数据源的运行

数据源卡片上显示状态（“正常”“已暂停”“失败”）、计划、上次运行时间和结果：行数、已接收、已跳过、失败。

• 立即运行：额外运行一次。它也会让数据源从暂停或失败状态恢复。
• 暂停 / 恢复：停止或继续按计划运行。
• 历史记录：运行列表，包括开始时间、触发方式（“按计划”或“手动”）、状态以及带行号的前几个行错误。

注意事项

• 如果文件自上次运行以来未发生变化，运行将以“无变化”状态结束，不会读取任何行。
• 一天内重复出现的同一行不会产生重复数据。
• 对于事件，系统会记住最后加载的事件时间：后续运行会跳过不晚于该时间的行。因此，历史文件只需在末尾追加即可。
• 出错的数据源会按计划重试，错误信息显示在卡片上。
• 已加载的事件计入套餐的每月配额。
• 删除数据源后，已加载的数据会保留。

如需连同历史数据一次性从 Mindbox 等平台迁移，可使用专门的工具，参见从其他平台迁移。