OneTrace.ru 帮助中心

接入网站

追踪器是放在您网站页面上的一小段脚本。它统计页面浏览、传递客户行为（浏览商品、加入购物车、下单、登录）、展示推荐小组件，并为访客订阅 Web Push。接入所需的一切都在用户互动 → 网站板块中。

此板块对所有项目成员开放。“所有者”“管理员”和“经理”可以修改网站域名和小组件。“所有者”和“管理员”可以创建网站密钥。

安装追踪器

安装选项卡包含三个步骤。

1. 用于每个页面的代码

  1. 在写入密钥字段中选择密钥。如果没有密钥，请点击创建网站密钥。
  2. 点击复制按钮复制代码。
  3. 将代码粘贴到网站所有页面的 <head> 中，通常放在公共页头模板里。

代码如下所示（板块中已填好地址和密钥）：

<script>
!function(w,d,u){var c=w.cdp=w.cdp||[];if(c.version)return;['init','page','track','identify','alias','reset','setLanguage','widgets','renderRecommendations'].forEach(function(m){c[m]=c[m]||function(){c.push([m].concat([].slice.call(arguments)))}});var s=d.createElement('script');s.async=1;s.src=u;d.head.appendChild(s)}(window,document,'https://cdp.onetrace.ru/tracker/cdp.js');
cdp.init('cdp_wk_…', { host: 'https://cdp.onetrace.ru' });
cdp.page();
</script>

脚本异步加载，不会拖慢网站。可以在代码之后立即调用 cdp.track()：这些调用会等待追踪器加载完成。追踪器会为每个浏览器分配一个持久的访客标识符（有效期一年的 cookie cdp_aid），并保存访问的 UTM 标签。

写入密钥在页面代码中可见，这是正常的：它只能用于发送事件。如果列表中的密钥不可选，说明它们是在此板块出现之前创建的，无法完整显示。请创建新的网站密钥，或使用网站上现有代码中的密钥。

“安装”选项卡：追踪代码和安装检查

2. 检查

安装后，打开网站的任意页面。几秒钟后，检查模块中会出现一个表格：域名、7 天内事件数和最新事件的时间。尚无事件时，板块会显示“正在等待首批事件”。板块打开期间，检查结果每 10 秒自动刷新一次。

3. 网站域名

为防止其他网站以您项目的名义发送事件和获取推荐，请指定您网站的域名：

  1. 输入域名，例如 shop.example.com，然后点击 +。检查表格中的域名可以通过添加到域名按钮添加。
  2. 点击保存。

域名同时允许其子域名：shop.ru 也允许 www.shop.ru。列表为空时，密钥可在任何网站上使用（“无限制”）。来自您服务器的请求不受此限制。最多可指定 20 个域名。

单页应用（SPA 和 PWA）

在 React、Vue、Angular 等构建的应用中页面不会重新加载，因此需要由应用自行发送页面浏览：每次切换界面后调用 cdp.page()，但首次加载不要重复调用——安装代码已经发送过。如果路由钩子在首次加载时也会触发（Vue Router 的 afterEach、React 的 useEffect），请改为从安装代码中移除 cdp.page()——安装选项卡中有示例。

// 每次切换界面后，路由已更新地址时
cdp.page();

// 没有独立地址的界面，或地址尚未更新
cdp.page('购物车', { path: '/cart', title: '购物车' });

如果某个界面没有独立地址（弹窗、结账步骤、不使用地址的 PWA），或路由稍后才更新地址，请显式传入页面：path 或 url（可以是相对地址）以及标题。该页面会记录到这次浏览以及后续事件的上下文中——例如加入购物车会关联到购物车界面——直到下一次调用 cdp.page()。对于第二个及之后的界面，跟踪器会把上一个界面作为来源，并在标签页关闭前保留本次访问的 UTM 标签。

客户登录和退出

在登录或注册后，使用用户在您系统中的 id 调用 cdp.identify()，访问历史就会与客户的档案关联：

cdp.identify('user-42', { email: 'anna@example.com' });

请仅为已登录用户传递 User ID，并且不要使用 0 或 guest 之类的通用值：User ID 相同的档案会被合并。退出账户时请调用 cdp.reset()，让下一个使用这台电脑的人获得新的标识符。

商品事件 选项卡中的 客户识别 表格列出了各渠道需要哪些标识符以及它们如何进入用户档案：电子邮件营销需要 email，按号码发送短信、WhatsApp 和 Viber 需要国际格式的 phone，Telegram 和 Viber 机器人则通过您服务器生成的链接关联聊天。请传入您了解的关于客户的一切信息：标识符越多，可用的渠道越多。

客户语言

跟踪器会发送浏览器语言，在语言被明确设置之前，它会保存到客户档案（language 属性）中。旅程和群发会根据此语言选择模板的语言版本。项目语言显示在安装选项卡的客户语言区块中。

如果网站有语言切换器，请上报访客的选择——它会被记住并保存到档案中：

cdp.setLanguage('de');

其他语言来源在初始化时设定：language: 'page' —— <html> 的 lang 属性，语言代码 —— 整个网站使用同一种语言，false —— 不发送语言。您系统中已知的语言可以作为特征传入：cdp.identify('user-42', { language: 'de' })。

商品事件

商品事件选项卡展示了五种操作的现成调用：商品浏览、加入购物车、订单、收藏以及登录和注册。事件名称和商品 id 属性（默认为 product_id）取自推荐板块的设置。如果那里尚未选择事件，您会看到警告，示例中将使用默认名称：product_viewed、add_to_cart、order_completed。

订单示例：所有商品都放在 products 数组中传递：

cdp.track('order_completed', {
  order_id: 'A-1001',
  amount: 9980,
  products: [{ product_id: 'SKU-1', quantity: 2, price: 4990 }],
});

收藏为可选步骤：add_to_wishlist 和 remove_from_wishlist 事件供通知收藏商品降价和到货的旅程使用。调用 cdp.addToWishlist('SKU-1') 和 cdp.removeFromWishlist('SKU-1')，或者无需代码：为按钮添加 data-cdp-wishlist="SKU-1"（添加）或 data-cdp-wishlist-remove="SKU-1"（移除）属性，跟踪器会在点击时自动发送事件。

每个步骤都有一个标记：7 天内收到了多少事件以及最新事件的时间，或“7 天内没有事件”。这样可以看出哪些调用尚未生效。商品 id 必须与商品目录中的 id 一致。

显示已接收事件标记的“商品事件”选项卡

订单和注册从您的服务器发送更可靠，参见服务器端集成。

邀请链接

如果在会员积分计划中启用了邀请，每位会员都会有一个指向您网站、带有 ?ref=邀请码 参数的链接。追踪器会自动识别该参数：将邀请码在 cookie cdp_ref 中保存 30 天，并发送一次 referral_visited 事件。好友在网站上注册或登录后即被计入。店铺插件会在注册时从 cookie 中传递邀请码，自建网站则通过 API 传递。

Web Push

Web Push 选项卡显示渠道是否已接入以及订阅数量。如果尚无渠道，请通过打开集成链接创建，密钥会自动生成（参见集成与渠道）。然后：

  1. **Service worker 文件。**在网站根目录创建 cdp-sw.js 文件，内容只有一行： 
    importScripts('https://cdp.onetrace.ru/tracker/cdp-sw.js');
  2. **订阅按钮。**在网站上添加一个按钮，点击时调用 cdp.push.subscribe()。浏览器只会在访客主动操作时请求通知权限。

通知仅在使用 HTTPS 的网站上有效。订阅会与访客的档案关联。

“Web Push”选项卡：渠道状态和网站代码

CMS 和 Google Tag Manager

CMS 和 GTM 选项卡提供了针对自建网站、Google Tag Manager、1C-Bitrix、Tilda、WordPress 和 WooCommerce、InSales 的分步说明：在哪里插入安装代码、事件和小组件。

例如，在 Google Tag Manager 中创建一个“自定义 HTML”代码，填入安装代码，并使用“所有网页”触发器。商品事件需要单独的代码，调用 cdp.track，并使用基于 dataLayer 事件（view_item、add_to_cart、purchase）的触发器。发布容器后，请在安装选项卡中确认事件已开始到达。

借助 AI 智能体接入

如果开发人员借助 AI 智能体（Claude Code、Codex、Cursor 等）开发您的网站，请将现成的技能交给智能体。在 AI 智能体 选项卡中点击 下载 SKILL.md。文件中包含面向智能体的英文说明以及您项目的数据：OneTrace.ru 地址、所选的写入密钥、商品事件名称、小组件和 Web Push 状态。智能体可据此自行添加安装代码、商品事件、登录和退出、小组件以及通知订阅。

  1. 如果有多个写入密钥，请选择所需的密钥。
  2. 下载文件并放入网站项目：Claude Code 放在 .claude/skills/<技能名称>/SKILL.md，其他支持 Agent Skills 的智能体放在其技能文件夹中，例如 .agents/skills/<技能名称>/SKILL.md。选项卡中显示了确切路径。也可以直接将文件附加到您发给智能体的消息中。
  3. 向智能体说明任务——选项卡中有示例文本。

“AI 智能体”选项卡：包含项目数据、供 AI 智能体使用的技能

秘密密钥绝不会写入技能。如果您在推荐设置中更改了事件或添加了小组件，请重新下载技能。

注意事项

  • 搜索引擎爬虫、即时通讯软件的链接预览、网站检测服务和自动化浏览器不会被统计：跟踪器不会发送它们的事件，也不会为其设置 cookie，但仍会显示推荐小组件。如需统计所有访客，请在安装代码中添加参数：cdp.init('…', { host: '…', ignoreBots: false })。
  • 追踪器会累积事件并批量发送。如果网络中断，事件会保存在浏览器中，稍后再发送。
  • 网站的所有事件都可以在事件板块中实时查看。
  • 推荐小组件在小组件选项卡中配置，参见网站推荐小组件。
← AI 助手（MCP） 网站推荐小组件 →