OneTrace.pro 帮助中心

文件导入与数据源

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

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

从 CSV 和 Excel 导入档案

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

文件要求

  • CSV 或 Excel 文件(.xlsx、.xls,第一个工作表),第一行为列标题。
  • 分隔符可以是逗号、分号或制表符,系统会自动识别。
  • 文件大小:CSV 不超过 20 MB,Excel 不超过 10 MB。
  • 至少包含一个标识符列:您系统中的客户 ID、邮箱或电话。
  • Excel 中日期格式的单元格按 2026-10-28 18:42:00 的形式载入,公式按其值载入。不支持 Excel 95 文件和受密码保护的文件:请另存为 .xlsx 或 CSV。

示例:

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

如何上传

  1. 点击选择文件并选择文件。
  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 服务账号密钥访问。请将表格以只读权限共享给该账号。
  • PostgreSQL、ClickHouse、BigQuery 或 Snowflake:您数据仓库中的表或查询,参见数据仓库。

文件格式:CSV、JSON(对象数组,不超过 50 MB)和 JSON Lines。

如何创建数据源

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

带列映射的数据源设置

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

对于门店小票,有线下小票模板和示例文件:它会填入购买事件、线下购买属性以及各列的提示:电话、会员卡、门店、小票号、金额和商品。参见门店与线下销售。

数据源的运行

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

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

数据源:显示状态和运行结果的卡片

注意事项

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

数据仓库

如果档案和订单已经汇集在您的数据仓库(PostgreSQL、ClickHouse、BigQuery 或 Snowflake)中,数据源可以直接从中读取。每次运行只获取自上次以来发生变化的行,因此即使是大表也无需导出为文件。变更会写入档案和事件,并据此触发旅程、重新计算分群。反方向的操作是导出到数据仓库。

从数据仓库读取在“企业版”套餐中提供,参见套餐。

连接

在集成板块的数据源分组中创建连接。字段与导出到该数据仓库时相同,但最好单独创建一个只读用户:

  • PostgreSQL:主机、端口、数据库,以及对所需表拥有 SELECT 权限的用户。
  • ClickHouse:HTTP 接口地址,以及拥有读取权限的用户。
  • BigQuery:拥有 BigQuery Data Viewer 和 BigQuery Job User 角色的服务账号密钥、项目和数据位置。
  • Snowflake:账户、使用密钥对的用户、拥有 SELECT 权限的角色,以及用于计算的 warehouse。读取时不需要 S3 存储桶。

数据仓库必须可从互联网访问:OneTrace.pro 不会访问内网地址。

数据源设置

按上文所述创建数据源,并选择数据仓库连接。其设置如下:

  • 读取内容:表(例如 public.customers 或 shop_dwh.customers)或自定义查询,即单条 SELECT 或 WITH 命令,不带 ;。OneTrace.pro 会为查询添加条件、排序和行数上限,因此无法通过查询修改数据。
  • 游标列:行的修改时间,例如 updated_at。每次运行读取该时间晚于上次运行的行。没有该时间的行不会被读取。
  • 行键:唯一列,例如 id 或 customer_id。用于区分修改时间相同的行。
  • 删除标记列:可选,例如 is_deleted。参见删除。

来自 BigQuery 数据仓库的数据源:表、游标、行键和列

其余步骤与文件相同:加载列、列映射、档案或事件、计划。

如何读取变更

  • 首次运行读取整张表,之后的运行只读取在上次读到的行之后发生变化的行。
  • 每次运行最多读取 100 万行。如果行数更多,下一次运行会立即开始,无需等待计划,因此大表的首次加载会连续分多次运行完成。
  • 如果运行中断,相同的行会被重新读取:档案只是再更新一次,重复的事件不会产生重复数据。
  • 更改表、查询、游标列或行键后,会从头开始读取。
  • 修改时间列必须由您的数据仓库更新:时间没有变化的行,OneTrace.pro 不会重新读取。
  • 查询以只读方式执行,并有时间限制:PostgreSQL、ClickHouse 和 Snowflake 为 10 分钟,BigQuery 为 15 分钟。

删除

如果档案数据源某一行的删除标记列为 true 或 1,OneTrace.pro 会删除带有该行标识符的档案,与 GDPR 请求的处理相同:连同历史记录、合并的档案以及导出中的数据一起删除。删除会记录在审计日志中,运行结果会显示删除了多少个档案。在事件数据源中,带标记的行会被直接跳过。

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