# 简介 (https://talivia.com/zh-CN/docs) Talivia 是为创始人和小型团队打造的收入优先型分析工具。它在同一个工作区中追踪访问、会话、来源、事件、产品使用路径、搜索词和付款，让您看清究竟是什么带来了收入。 Talivia 将数据分析与付款归因结合起来，提供会话级收入分析、Stripe、Yolfi 和 Dodo Payments 原生连接、手动付款接口、搜索平台集成，以及与其他用户共享网站的实用协作功能。 ## Talivia 追踪哪些数据 [#talivia-追踪哪些数据] * 访问、会话、页面、引荐来源、推广活动、国家和地区、设备、浏览器及操作系统。 * 通过数据属性或 `window.talivia.track` 发送的自定义事件。 * 为网站启用后采集的会话回放和网页核心性能指标。 * 来自已连接付款服务商、结账返回网址及手动付款接口的收入。 * 来自 Google Search Console 和必应网站管理员工具的搜索词，以及按搜索词估算分配的收入。 ## 建议的配置顺序 [#建议的配置顺序] 1. 添加网站。 2. 安装追踪脚本。 3. 确认数据看板中已出现访问记录。 4. 结账流程准备好后连接收入来源。 5. 如需其他人访问，请邀请团队成员或只读用户。 ## 如何使用这些文档 [#如何使用这些文档] 如果只需安装脚本，请从**安装**开始。JavaScript 和数据属性示例请查看**数据追踪**。需要将付款关联到会话和流量来源时，请查看**收入**与**归因**。 --- # 人工智能代理与模型上下文协议 (https://talivia.com/zh-CN/docs/ai-agents) Talivia 在以下地址提供账户级[模型上下文协议](https://modelcontextprotocol.io/)端点： ```text https://talivia.com/mcp ``` 只需连接一次，获得授权的人工智能代理便可处理 Talivia 账户有权访问的所有网站。代理可以检查配置、创建或选择网站、获取准确的追踪代码和框架安装说明、打开安全的付款服务商配置流程，并验证真实数据是否已经到达。 ## 选择客户端 [#选择客户端] Codex 通过命令行、远程模型上下文协议和 OAuth 连接。 ChatGPT 在“应用与连接器”中创建自定义应用。 Claude 将 Talivia 添加为自定义网页连接器。 其他客户端 使用可流式传输的 HTTP 与 OAuth 发现。 ## 授权如何工作 [#授权如何工作] 1. 将 `https://talivia.com/mcp` 添加到模型上下文协议客户端。 2. 第一个受保护请求会返回 OAuth 质询，其中包含 Talivia 授权元数据。 3. 客户端会在浏览器中打开 Talivia；如有需要，请先登录。 4. 检查请求的权限范围并批准连接。 5. 客户端会收到短期访问令牌。令牌过期后，Talivia 会要求重新授权，而不会签发长期刷新凭据。 代理永远不会收到您的 Talivia 密码。付款服务商密钥也会保留在 Talivia 内：Stripe 等服务商需要授权时，工具会返回安全的浏览器移交，而不是要求代理处理凭据。 您可以随时在**设置 → 人工智能代理**中查看或撤销已批准连接。 ## 本地 npm 桥接器 [#本地-npm-桥接器] 如果客户端需要本地标准输入输出协议服务器，请使用已发布的 Talivia 软件包： ```bash npx -y @talivia/agent setup --agent codex npx -y @talivia/agent checkin --agent codex codex mcp add talivia -- npx -y @talivia/agent mcp ``` 配置命令会打开 Talivia 进行浏览器批准。签入命令将已批准且可撤销的本地凭据保存到 `~/.talivia/config.json`，最后一条命令让 Codex 启动经过身份验证的标准输入输出桥接器。 ## Codex [#codex] 添加托管端点： ```bash codex mcp add talivia --url https://talivia.com/mcp ``` 然后开始浏览器授权： ```bash codex mcp login talivia ``` 批准后，可以这样要求 Codex： ```text 请为这个项目配置 Talivia。选择或创建正确的网站，安装追踪器，通过安全的浏览器移交连接收入，并验证真实数据已经到达。 ``` ## ChatGPT [#chatgpt] 1. 打开 **ChatGPT → 设置 → 应用与连接器**。 2. 创建名为 `Talivia` 的自定义应用。 3. 将服务器网址设为 `https://talivia.com/mcp`，并选择 OAuth。 4. 保存应用，然后在浏览器中完成 Talivia 登录与授权同意。 5. 在对话中启用 Talivia，再要求它检查或完成配置。 ## Claude [#claude] 1. 打开 **Claude → 自定义 → 连接器 → 添加自定义连接器**。 2. 将连接器命名为 `Talivia`，远程服务器网址使用 `https://talivia.com/mcp`。 3. 在浏览器中完成 Talivia 登录与授权同意。 4. 在对话中打开 `+` 菜单，选择**连接器**并启用 Talivia。 ## Claude Code [#claude-code] 注册托管端点： ```bash claude mcp add --transport http talivia https://talivia.com/mcp ``` 首次调用受保护工具时会启动浏览器授权。 ## 其他模型上下文协议客户端 [#其他模型上下文协议客户端] 使用支持 OAuth 发现的可流式传输 HTTP 服务器： ```json { "talivia": { "type": "http", "url": "https://talivia.com/mcp", "auth": "oauth" } } ``` 客户端必须支持模型上下文协议 OAuth 授权服务器发现和浏览器授权流程。如果不支持，请使用上方列出的客户端。 ## 代理可以执行哪些操作 [#代理可以执行哪些操作] Talivia 刻意只提供一组精简工具： * 检查已登录账户并列出可访问网站。 * 只有用户确认后才创建网站。 * 返回准确追踪代码和特定框架的安装方案。 * 检查完整配置清单，并验证实时追踪数据已被接收。 * 启动安全的付款服务商配置，并读取连接状态。 * 在不暴露付款凭据的前提下提供结账归因指南。 ## 问题排查 [#问题排查] ### 浏览器没有打开 [#浏览器没有打开] 确认客户端支持远程服务器 OAuth。删除已有 Talivia 条目，重新添加并再次授权。 ### 端点不可用 [#端点不可用] 打开**设置 → 人工智能代理**并检查端点状态。健康的端点会显示**可以连接**。 ### 授权了错误账户 [#授权了错误账户] 在**设置 → 人工智能代理**中撤销连接，在浏览器中登录目标 Talivia 账户，然后重新连接。 ### 代理看不到某个网站 [#代理看不到某个网站] 模型上下文协议连接遵循与 Talivia 界面相同的账户和网站权限。请确认当前账户有权访问该网站。 --- # 跨域追踪 (https://talivia.com/zh-CN/docs/cross-domain-tracking) 浏览器无法在互不相关的根域名之间共享 Cookie，因此 Talivia 使用短期有效的签名连接令牌。 1. 打开**设置 → 归因**。 2. 添加访问路径中用到的每一个自有根域名。 3. 保持**跨域追踪**开启。 4. 从**设置 → 数据追踪**复制更新后的代码片段，并安装到每个域名。 生成的代码片段包含 `data-cross-domain-domains`。收到首次追踪响应后，Talivia 会为指向匹配域名的链接添加 `_tlv`。目标网站会验证签名、延续匿名访客与会话，并在保存页面浏览记录之前从地址中移除 `_tlv`。 连接令牌五分钟后失效，并且只适用于一个 Talivia 网站编号。令牌经过修改、已经过期或由其他网站签发时都会被拒绝。 子域名之间不需要连接令牌。对于 `example.com` 和 `app.example.com`，请使用[子域名追踪](https://talivia.com/zh-CN/docs/subdomain-tracking)。 --- # 唯一标识符 (https://talivia.com/zh-CN/docs/distinct-ids) Talivia 默认进行匿名追踪。追踪器会在浏览器存储中创建访客键和会话键，无需用户编号即可记录页面浏览。 当应用已经知道访客身份时，请使用 `identify`。 ```js window.talivia.identify('user_123', { email: 'founder@example.com', name: 'Founder', }); ``` ## 付款客户字段 [#付款客户字段] Talivia 能够识别常见的付款和客户字段： ```js window.talivia.identify('user_123', { stripeCustomerId: 'cus_123', providerName: 'stripe', providerCustomerId: 'cus_123', externalCustomerId: 'user_123', emailHash: 'sha256-email-hash', }); ``` 这些字段有助于将 Stripe 或手动付款重新关联到访客，尤其适用于稍后才进行结账的情况。 ## identify 会执行什么操作 [#identify-会执行什么操作] `identify` 会发送一个身份识别采集事件、保存会话数据，并将当前访客和会话关联到客户身份。 ## 应在何时调用 [#应在何时调用] 请在登录、注册、创建账户或创建新付款客户后调用 `identify`。 --- # 目标 (https://talivia.com/zh-CN/docs/goals) 目标用于定义重要的业务结果，并持续观察转化率的变化。 ## 目标示例 [#目标示例] * 访问 `/pricing`。 * 触发 `signup-click` 等自定义事件。 * 到达结账返回页面。 * 会话属性或事件数据符合指定条件。 ## 如何使用目标 [#如何使用目标] 在网站报表区域中创建目标。选择代表成功的条件，然后在所选日期范围内查看转化次数和转化率。 ## 收入目标 [#收入目标] 分析付费转化时，建议优先使用“收入”和“归因”报表。目标更适合衡量可能发生在付款之前的产品里程碑。 --- # 安装 (https://talivia.com/zh-CN/docs/install) 安装分为两个实用步骤：先把追踪器加入网站，再连接实际产生收入的付款系统。 ## 第 1 步：安装追踪器 [#第-1-步安装追踪器] 只要能够添加脚本标签，就可以使用 Talivia 追踪器。请先采用通用代码片段；只有在需要确认特定技术栈的准确放置位置时，才需要查看框架指南。 ### 通用代码片段 [#通用代码片段] 在应用中打开网站，前往**设置 → 数据追踪**，复制为该网站生成的代码片段。 ```html ``` 请始终从网站设置中复制代码片段。请用 Talivia 的“设置 → 数据追踪”中显示的真实编号替换 YOUR\_WEBSITE\_ID，不要重复使用示例值。 将代码片段放在 `` 结束标签之前，或通过框架共用的文档或布局组件加载。 Talivia 云服务生成的代码片段通常包含 `data-domain`。只有一个主机名的网站不设置它也能工作，但保留生成值可以让根网站及其子域名共享同一访客和活动后延长 30 分钟的会话。常规安装无需手动添加或删除此属性。 如果访问流程会跳转到另一个根域名，请在**设置 → 归因**中添加自有域名，然后复制更新后的代码片段。 追踪概览 了解脚本会自动记录什么，以及它提供哪些运行时函数。 追踪器配置 了解可选脚本属性、存储、筛选和数据采集设置。 子域名追踪 让根网站、应用、文档和结账页面共享同一访客身份。 ### 框架与建站工具指南 [#框架与建站工具指南] 如果网站使用框架、内容管理系统、电商平台或无代码建站工具，请在下方打开相应指南，查看同一段代码的准确粘贴位置。框架示例主要说明放置位置，可能省略可选属性；实际安装时请使用**设置 → 数据追踪**中生成的完整代码。 Next.js 应用路由器与共用布局。 React Vite、Create React App 与静态 HTML 外壳。 Vue Vue 应用与共用 HTML 入口。 Nuxt 应用头部与插件配置。 Angular 工作区 index.html 或运行时注入。 SvelteKit 全局应用模板。 Astro 基础布局与内容网站。 Remix 根文档与 Scripts 组件。 SolidStart 根文档配置。 Qwik 根布局与头部放置位置。 Gatsby 服务端渲染文档钩子。 Expo Expo 网页版与静态 HTML。 Laravel Blade 布局与共用应用视图。 Django 基础模板与继承页面。 Ruby on Rails 应用布局与 ERB 模板。 Express EJS、Pug 或静态 HTML 外壳。 NestJS 服务端渲染模板或静态客户端。 Flask Jinja 基础模板。 Phoenix 根布局与 LiveView 页面。 WordPress 主题页脚、子主题或代码片段插件。 Shopify 主题布局与店面页面。 Wix 控制台中的自定义代码设置。 Webflow 网站自定义代码与项目设置。 Squarespace 为所有页面注入代码。 Framer 在 body 结束标签之前添加自定义代码。 Tilda 在全站 body 结束标签之前添加 HTML。 ## 第 2 步：连接付款 [#第-2-步连接付款] 只有 Talivia 能够看到付款事件后，流量数据才会成为有用的收入分析。请选择与结账方式匹配的付款路径。 Stripe 连接受限接口密钥，由 Talivia 配置网络回调。 Yolfi 连接账户并配置结账会话返回网址。 LemonSqueezy 通过 LemonSqueezy 结账时使用服务商事件。 Polar 产品通过 Polar 销售时使用 Polar 付款事件。 Dodo Payments 连接一个接口密钥；Talivia 会创建付款与退款网络回调。 手动付款接口 从后端或自定义付款处理系统发送付款。 对于能够在返回网址中提供唯一结账编号的托管服务商，请配置该服务商要求的返回占位符。自定义付款流程应把 `window.talivia.getSessionId()` 作为服务商支持的元数据传递，或作为 `sessionId` 发送给手动付款接口。各收入指南会说明服务商最推荐的信号。 ## 验证安装 [#验证安装] 1. 在普通浏览器标签页中打开网站。 2. 访问一个包含追踪器的页面。 3. 返回 Talivia 并打开该网站的数据看板。 4. 确认出现了新的会话、页面浏览、引荐来源、浏览器和国家或地区。 5. 完成付款配置后进行一笔测试付款，并确认收入出现在同一个网站中。 --- # Angular (https://talivia.com/zh-CN/docs/installation-guides/angular) 对于 Angular 应用，请将追踪器加入包裹整个应用的 HTML 外壳。 ## 添加脚本 [#添加脚本] 打开 `src/index.html`，将代码片段放在 `` 结束标签之前。 ```html ``` 请替换网站编号。使用 Talivia“设置 → 数据追踪”中这个 Angular 域名对应的编号。 构建或运行应用、打开页面，然后在 Talivia 中确认首次会话。 --- # Astro (https://talivia.com/zh-CN/docs/installation-guides/astro) 请将 Talivia 加入所有 Astro 页面共用的布局。 ## 添加脚本 [#添加脚本] 打开基础布局（例如 `src/layouts/BaseLayout.astro`），将代码片段放在 `` 结束标签之前。 ```astro --- const { title } = Astro.props; --- {title} ``` 请替换网站编号。使用 Talivia“设置 → 数据追踪”中这个 Astro 网站对应的编号。 部署或运行网站、访问一个页面，然后在 Talivia 中确认新会话。 --- # Django (https://talivia.com/zh-CN/docs/installation-guides/django) 请在所有公开页面继承的基础模板中安装 Talivia。 ## 基础模板 [#基础模板] 打开 `templates/base.html` 等共用模板，将代码片段放在 `` 之前。 ```html ``` 如果网站不同区域使用不同基础模板，请将 Talivia 加入每个公开基础模板。 请勿保留占位符。 请用 Talivia“设置 → 数据追踪”中的值替换 YOUR_WEBSITE_ID 。 部署模板、访问页面，然后在 Talivia 中确认首次会话。 --- # Expo (https://talivia.com/zh-CN/docs/installation-guides/expo) Talivia 的浏览器追踪器适用于网页。本指南适用于 Expo Web 或 Expo Router 应用的网页构建。 ## Expo Router [#expo-router] 创建或更新 `app/+html.tsx`，并将脚本放入 body。 ```tsx import { ScrollViewStyleReset } from 'expo-router/html'; export default function Root({ children }: { children: React.ReactNode }) { return ( {children} ``` 原生应用需要采用其他方式。此脚本只追踪浏览器流量，可用于 Expo Web，但不能追踪 iOS 或 Android 原生界面。 --- # Express (https://talivia.com/zh-CN/docs/installation-guides/express) 请使用包裹 Express 页面内容的共用 HTML 模板。 ## 模板应用 [#模板应用] 如果使用 EJS、Pug、Handlebars 或其他视图引擎，请将代码片段放入基础布局的 `` 之前。 ```html
``` ## 静态应用 [#静态应用] 如果 Express 提供静态前端，请将代码片段加入生成的 `index.html`。 请替换网站编号。 使用 Talivia“设置 → 数据追踪”中的值。 重启服务器、打开页面，然后在 Talivia 中验证会话。 --- # Flask (https://talivia.com/zh-CN/docs/installation-guides/flask) 请将 Talivia 加入页面使用的 Jinja 基础模板。 ## 添加脚本 [#添加脚本] 打开通常位于 `templates/base.html` 的基础模板，将代码片段放在 `` 之前。 ```html {% block content %}{% endblock %} ``` 请替换网站编号。 使用 Talivia“设置 → 数据追踪”中的值。 运行 Flask、打开页面，并确认 Talivia 收到了会话。 --- # Framer (https://talivia.com/zh-CN/docs/installation-guides/framer) 使用 Framer 自定义代码，在整个已发布网站中加载 Talivia。 ## 添加自定义代码 [#添加自定义代码] 1. 打开 Framer 项目。 2. 前往网站设置。 3. 打开自定义代码区域。 4. 在 body 结束标签之前添加 Talivia 代码片段。 5. 发布网站。 ```html ``` 请替换网站编号。 从 Talivia 的“设置 → 数据追踪”复制该 Framer 网站编号。 访问已发布网站，并验证首个 Talivia 会话。 --- # Gatsby (https://talivia.com/zh-CN/docs/installation-guides/gatsby) 使用 Gatsby 的服务端渲染钩子，让 Talivia 出现在每个生成页面中。 ## 添加脚本 [#添加脚本] 创建或打开 `gatsby-ssr.js`，将 Talivia 脚本追加到 body 后置组件。 ```jsx import React from 'react'; export const onRenderBody = ({ setPostBodyComponents }) => { setPostBodyComponents([ ``` 如果营销网站使用其他布局，请改为在那个布局中添加代码。 请使用 Talivia 中的网站编号。 每个 Laravel 应用或域名都应使用为相应网站生成的编号。 ## 验证 [#验证] 在浏览器中访问 Laravel 网站，然后打开 Talivia，确认网站数据看板出现了新会话。 --- # NestJS (https://talivia.com/zh-CN/docs/installation-guides/nest-js) NestJS 可以提供模板或独立前端。请在生成浏览器 HTML 外壳的位置添加 Talivia。 ## 服务端渲染模板 [#服务端渲染模板] 将代码片段放在共用布局或模板的 `` 结束标签之前。 ```html
``` ## 仅提供接口的应用 [#仅提供接口的应用] 如果 NestJS 只提供接口，请改在 Next.js、React、Angular 或 Vue 等前端应用中安装 Talivia。 请替换网站编号。 从 Talivia 的“设置 → 数据追踪”复制公开网站编号。 打开公开应用，并在 Talivia 中验证首次会话。 --- # Next.js (https://talivia.com/zh-CN/docs/installation-guides/next-js) 请使用根布局，让追踪器在每个路由中加载。 ## 应用路由器 [#应用路由器] 打开 `app/layout.tsx` 并添加 `next/script`。 ```tsx import Script from 'next/script'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ``` 请替换网站编号。 从 Talivia 的“设置 → 数据追踪”复制编号。 打开 Phoenix 网站，并在 Talivia 中确认新访问。 --- # Qwik (https://talivia.com/zh-CN/docs/installation-guides/qwik) 使用根布局，让每个公开页面都包含追踪器。 ## 添加脚本 [#添加脚本] 打开根布局或文档文件，在 body 末尾附近添加 Talivia 代码片段。 ```tsx export default component$(() => { return ( <> ``` ## Create React App [#create-react-app] 打开 `public/index.html`，将代码片段放在 `` 结束标签之前。 ```html
``` 请使用自己的 Talivia 网站编号。示例编号只是占位符。 Talivia 会监测浏览器历史记录变化，因此脚本加载后也会追踪 React Router 的路由切换。 --- # Remix (https://talivia.com/zh-CN/docs/installation-guides/remix) 使用根文档，让每个路由都包含追踪器。 ## 添加脚本 [#添加脚本] 打开 `app/root.tsx`，将代码片段放在 Remix 的 `Scripts` 组件之前。 ```tsx import { Links, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'; export default function App() { return ( ``` 请替换网站编号。 从 Talivia 的“设置 → 数据追踪”复制此 Rails 域名的编号。 在浏览器中打开 Rails 应用，并在 Talivia 中确认新会话。 --- # Shopify (https://talivia.com/zh-CN/docs/installation-guides/shopify) 请在 Shopify 主题布局中安装 Talivia，以追踪店面页面。 ## 主题布局 [#主题布局] 打开 Shopify 主题代码编辑器并编辑 `layout/theme.liquid`，将代码片段放在 `` 之前。 ```html ``` 先追踪店面。 此方式会追踪呈现主题的在线商店页面。根据 Shopify 套餐和配置，结账页面可能需要单独处理。 ## 验证 [#验证] 预览或发布主题，访问商品页或落地页，并确认访问出现在 Talivia 中。 --- # SolidStart (https://talivia.com/zh-CN/docs/installation-guides/solid-start) 将 Talivia 加入根文档，使其在整个应用中加载。 ## 添加脚本 [#添加脚本] 打开定义 `StartServer`、`Scripts` 或文档 body 的根入口文件，然后在 body 结束之前放入代码片段。 ```tsx import { Scripts } from '@solidjs/start'; export default function Root() { return ( ``` 请替换网站编号。 使用 Talivia“设置 → 数据追踪”中的编号。 打开已发布的 Squarespace 网站，并在 Talivia 中确认新会话。 --- # SvelteKit (https://talivia.com/zh-CN/docs/installation-guides/svelte-kit) 使用应用模板，让 Talivia 在整个 SvelteKit 网站中只加载一次。 ## 添加脚本 [#添加脚本] 打开 `src/app.html`，将代码片段放在 `` 结束标签之前。 ```html
%sveltekit.body%
``` 请替换网站编号。从 Talivia 的“设置 → 数据追踪”复制编号。 脚本加载后，Talivia 会追踪普通页面浏览以及客户端路由切换。 --- # Tilda (https://talivia.com/zh-CN/docs/installation-guides/tilda) 将 Talivia 作为全站 HTML 添加，以追踪每个已发布页面。 ## 全站代码 [#全站代码] 1. 打开 Tilda 项目设置。 2. 找到自定义代码或 HTML 注入区域。 3. 将 Talivia 脚本粘贴到 body 结束标签之前。 4. 重新发布项目。 ```html ``` 请使用正确的网站编号。 如果有多个 Tilda 域名或项目，每个都应使用自己的 Talivia 网站编号。 发布后打开线上网站，并在 Talivia 中检查页面浏览记录。 --- # Vue (https://talivia.com/zh-CN/docs/installation-guides/vue) 请将 Talivia 脚本加入加载 Vue 应用的 HTML 文件。 ## 使用 Vite 的 Vue [#使用-vite-的-vue] 打开 `index.html`，将代码片段放在 `body` 末尾附近。 ```html
``` ## 类似 Nuxt 的项目 [#类似-nuxt-的项目] 如果 Vue 项目提供全局应用模板或头部/脚本配置，请只在全局加入一次相同的追踪器，不要在各个页面中重复添加。 ```html ``` 请替换 YOUR\_WEBSITE\_ID。从 Talivia 的“设置 → 数据追踪”复制真实值。 部署后打开任意公开页面，并在 Talivia 数据看板中确认出现了新访问。 --- # Webflow (https://talivia.com/zh-CN/docs/installation-guides/webflow) 使用 Webflow 自定义代码，让每个已发布页面都包含 Talivia。 ## 添加自定义代码 [#添加自定义代码] 1. 打开 Webflow 项目。 2. 前往项目设置。 3. 打开自定义代码区域。 4. 将 Talivia 代码片段粘贴到 body 结束标签之前。 5. 保存更改并发布网站。 ```html ``` 请替换网站编号。 从 Talivia 的“设置 → 数据追踪”复制 Webflow 域名编号。 访问已发布网站，并在 Talivia 中验证新会话。 --- # Wix (https://talivia.com/zh-CN/docs/installation-guides/wix) 使用 Wix 自定义代码，在每个公开页面中加载 Talivia。 ## 添加自定义代码 [#添加自定义代码] 1. 打开 Wix 控制台。 2. 前往网站的自定义代码或追踪工具区域。 3. 添加新的自定义代码片段。 4. 粘贴 Talivia 脚本。 5. 设置为在所有页面的 body 末尾附近加载。 ```html ``` 请替换网站编号。 从 Talivia 的“设置 → 数据追踪”复制要衡量的 Wix 域名编号。 发布 Wix 网站、在浏览器中打开，并在 Talivia 中验证新访问。 --- # WordPress (https://talivia.com/zh-CN/docs/installation-guides/wordpress) 最稳妥的 WordPress 配置方式，是通过子主题或可信的自定义代码插件在全站添加一次 Talivia。 ## 方案 1：子主题 [#方案-1子主题] 在子主题的 `functions.php` 中通过 `wp_footer` 钩子添加脚本。 ```php add_action('wp_footer', function () { ?> ` 结束标签前插入代码的插件，并粘贴通用代码片段。 ```html ``` 请在全站安装。 只需全局添加一次追踪器，不要在每篇文章中重复添加。 在普通浏览器标签页中打开 WordPress 网站，并在 Talivia 中确认新会话。 --- # 集成 (https://talivia.com/zh-CN/docs/integrations) 集成可以补充浏览器追踪器无法自行采集的上下文。连接平台后，便可将平台活动与访客、收入及其他网站指标放在一起查看。 X 提及监测 将有关产品或网站的讨论与流量和收入放在一起查看。 GitHub 提交记录 在分析图表上查看最近的代码提交，找出真正推动指标变化的改动。 --- # 人工智能机器人流量跟踪 (https://talivia.com/zh-CN/docs/integrations/bot-traffic) # 人工智能机器人流量跟踪 [#人工智能机器人流量跟踪] 机器人流量是 **Talivia Cloud** 的服务器端功能。已识别的爬虫请求会存入独立数据集，不会计入真人浏览量、访客、转化或收入。 记录请求只表示匹配的爬虫访问了某个 URL，并不能证明内容被引用、推荐、用于回答、身份经过密码学验证或产生收入影响。 ## 1. 创建网站令牌 [#1-创建网站令牌] 打开**网站设置 → 机器人流量**，启用收集并生成令牌。每个令牌只属于一个网站。令牌只显示一次，请立即复制，并作为服务器端密钥保存。轮换令牌会立即撤销旧令牌。 ```bash pnpm add @talivia/bot-traffic ``` ```bash TALIVIA_BOT_TOKEN= ``` ## Next.js middleware 或 proxy [#nextjs-middleware-或-proxy] Next middleware 在最终页面响应之前运行。请使用仅请求跟踪；`NextResponse.next()` 不是页面的最终状态码，不能作为最终状态上报。 ```ts import { NextResponse } from 'next/server'; import { trackBotRequestInBackground } from '@talivia/bot-traffic/next'; export function middleware(request, event) { trackBotRequestInBackground( request, { token: process.env.TALIVIA_BOT_TOKEN! }, event, ); return NextResponse.next(); } export const config = { matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'] }; ``` ## Express [#express] Express 适配器会立即调用 `next()`，并在响应的 `finish` 事件后上报最终状态码。 ```ts import express from 'express'; import { createExpressBotMiddleware } from '@talivia/bot-traffic/express'; const app = express(); app.use(createExpressBotMiddleware({ token: process.env.TALIVIA_BOT_TOKEN!, })); ``` ## Cloudflare Workers 和 Pages [#cloudflare-workers-和-pages] ```ts import { withBotTracking } from '@talivia/bot-traffic/cloudflare'; export default { fetch: withBotTracking( (request, env) => env.ASSETS.fetch(request), { token: '' }, ), }; ``` 对于 Pages Functions，先处理 `context.request`，然后使用最终状态码调用 `trackBotRequestInBackground`，并将 `context` 作为第三个参数传入，以便通过 `waitUntil` 完成后台发送。 ## 任意 JavaScript 或 TypeScript 框架 [#任意-javascript-或-typescript-框架] 如果框架提供标准 `Request` 和 `Response`，则不需要专用适配器： ```ts import { trackBotRequestInBackground } from '@talivia/bot-traffic'; export async function handle(request, context) { const response = await yourFrameworkHandler(request); trackBotRequestInBackground( request, { token: process.env.TALIVIA_BOT_TOKEN!, status: response.status }, context, ); return response; } ``` 如果只能获得传入请求，请省略 `status`。仅请求跟踪仍可记录爬虫尝试访问的页面。只有当 handler 返回最终 `Response` 时才使用 `withBotTracking`。该通用模式适用于 Hono、Bun、Deno、自定义 Node.js Fetch 服务和其他兼容 Fetch 的运行时。 ## Docker、Cloud Run 和反向代理 [#dockercloud-run-和反向代理] 如果 `request.url` 使用内部主机名，例如 `http://app:3000/docs`，请设置真实的公开 origin： ```ts { token: process.env.TALIVIA_BOT_TOKEN!, publicOrigin: 'https://example.com', } ``` 软件包只替换 origin，并保留请求路径。`publicOrigin` 必须是没有用户名、密码、路径、查询参数或 fragment 的 `http` 或 `https` origin。Talivia 仍会验证公开主机名是否属于该令牌对应的网站。 ## PHP、Go、Ruby 和其他语言 [#phpgoruby-和其他语言] JavaScript 软件包不是必需的。任何服务器语言都可以向固定 endpoint 发送最小事件： ```http POST https://talivia.com/v1/bot-traffic Authorization: Bearer Content-Type: application/json { "schemaVersion": 1, "hostname": "example.com", "path": "/docs/getting-started", "method": "GET", "userAgent": "GPTBot/1.0", "status": 200 } ``` `status` 是可选字段。Talivia Cloud 会自行确定 provider、bot、category 和 verification，不需要发送这些字段。 ### PHP 示例 [#php-示例] 只能在应用已经发送用户响应之后调用此 helper。使用 PHP-FPM 时，如果可用，请先调用 `fastcgi_finish_request()`。 ```php function trackTaliviaBot(array $event, string $token): void { $ch = curl_init('https://talivia.com/v1/bot-traffic'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($event, JSON_UNESCAPED_SLASHES), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $token, 'Content-Type: application/json', ], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT_MS => 1500, ]); curl_exec($ch); curl_close($ch); } // 框架生成并发送最终响应之后： if (function_exists('fastcgi_finish_request')) { fastcgi_finish_request(); } trackTaliviaBot($event, getenv('TALIVIA_BOT_TOKEN')); ``` 只对可能是爬虫的文档类 `GET` 或 `HEAD` 请求调用该 helper，并且必须在最终状态码已知且用户响应已经发送之后调用。`path` 只能发送 pathname，不应包含查询参数或 fragment。不要发送 Cookie、Authorization 请求头、请求正文、访客标识、referrer 或来源 IP。 ## 自定义接入要求 [#自定义接入要求] * Endpoint：`https://talivia.com/v1/bot-traffic`。 * 鉴权：`Authorization: Bearer `。 * Content type：`application/json`。 * 必填字段：`schemaVersion`、`hostname`、`path`、`method`、`userAgent`。 * 可选字段：`status`，范围为 `100` 到 `599`。 * 只处理文档类 `GET` 和 `HEAD` 请求。 * Payload 不超过 8 KiB，User-Agent 不超过 512 个字符。 * 从 `path` 中删除查询参数和 fragment。 * 使用短超时并保持 fail-open；遥测失败不得影响或延迟网站响应。 * User-Agent 不能证明真实身份。Talivia 会执行中央分类和网络验证。 部署后，可在详细报告中查看请求趋势、提供商、类别、页面、状态码、缺失页面以及基于证据的验证可信度。 --- # 显示 GitHub 提交记录 (https://talivia.com/zh-CN/docs/integrations/github-commits) 安装 Talivia GitHub 应用，即可在分析图表上查看最近提交，判断哪些改动产生了实际影响。提交会作为主图表标记出现，让您把发布的改动与之后的访客和收入联系起来。 ## 为什么显示提交记录 [#为什么显示提交记录] 提交记录能为网站分析补充有用背景： * 准确了解流量或收入变化之前发布了什么。 * 长期比较发布活动与转化趋势。 * 分享一张让整个团队看清变化前因后果的图表。 ## 工作原理 [#工作原理] 在账户或组织中安装 Talivia GitHub 应用，并授予一个代码仓库的只读权限。Talivia 会导入默认分支的最新提交，并每 20 分钟检查一次新提交，保持自动同步。 将指针移到图表上的提交标记即可预览提交消息。选择标记可查看该时刻的完整列表，并在 GitHub 上打开任意提交。 应用只请求代码仓库内容的读取权限。Talivia 永远不会保存代码，只保存图表上显示的提交元数据：消息、作者和时间。 ## 连接代码仓库 [#连接代码仓库] 1. 在 Talivia 中打开网站。 2. 前往**设置 → 集成**。 3. 找到 **GitHub** 集成并选择**连接 GitHub**。 4. 在 GitHub 账户或组织中安装应用，并选择该网站对应的代码仓库。 如果只授予一个仓库的权限，它会自动连接，Talivia 会回填最近 30 天内最多 300 条提交。如果授予多个仓库，返回设置页面后请选择属于该网站的仓库。 ## 使用提交记录理解指标变化 [#使用提交记录理解指标变化] 发现图表变化时： 1. 查找同一时间附近显示的提交。 2. 将指针移到标记上查看发布内容。 3. 比较部署与访客或收入变化。 4. 需要查看完整差异时，在 GitHub 上打开提交。 提交记录提供背景，并不代表确定归因。请结合引荐来源、推广活动和收入数据判断最可能影响变化的因素。 --- # 追踪 X 平台提及 (https://talivia.com/zh-CN/docs/integrations/x-mentions) 访客或收入突然增长时，原因未必显而易见。X 提及监测会把相关讨论加入分析图表，帮助您判断当时是否有人在讨论产品或网站。 ## 为什么追踪 X 提及 [#为什么追踪-x-提及] X 提及能为网站分析补充有用背景： * 理解意外的流量和收入峰值。 * 发现关于产品或网站的讨论。 * 查看网站活动变化时人们在谈论什么。 * 找出值得回复或分享的帖子。 ## 工作原理 [#工作原理] Talivia 会在 X 上检查产品或网站提及，并把匹配帖子显示在主要分析图表上。 将指针移到图表中的提及标记上即可预览讨论。选择标记可查看该时刻的完整列表，并在 X 上打开原帖。 提及与访客和收入并列显示，因此无需在多个工具之间切换，就能比较讨论与网站上实际发生的变化。 ## 配置 X 提及监测 [#配置-x-提及监测] 1. 在 Talivia 中打开网站。 2. 前往**设置 → 集成**。 3. 找到 **X** 集成并选择**连接**。 仅需这些操作。连接后提及监测会自动开始，无需手动同步。Talivia 使用网站设置中已有的产品名称和网站地址，无需另行配置。 ## 使用提及理解指标峰值 [#使用提及理解指标峰值] 发现图表变化时： 1. 查找同一时间附近显示的提及。 2. 将指针移到标记上阅读相关帖子。 3. 比较讨论与访客或收入变化。 4. 需要查看完整讨论时，在 X 上打开相关帖子。 提及提供背景，并不代表确定归因。请结合引荐来源、推广活动和收入数据判断最可能影响变化的因素。 --- # 追踪链接 (https://talivia.com/zh-CN/docs/links) 追踪链接是重定向网址。即使未安装完整的网站脚本，Talivia 也可以单独追踪这些链接。 在**追踪链接**中创建链接、设置目标网址，然后复制生成的网址。 ```txt https://talivia.com/q/abc123xyz ``` 有人打开链接时，Talivia 会记录一个链接事件，然后将访客重定向到目标网址。 ## 适用场景 [#适用场景] * 邮件简报中的链接。 * 社交资料中的链接。 * 联盟推广链接。 * 赞助内容卡片。 * 无法安装脚本的推广网址。 ## 报表 [#报表] 追踪链接报表使用与网站相同的核心分析面板，包括访客、引荐来源、国家和地区、设备、事件及日期筛选。 截图占位：包含目标网址和已生成追踪链接的链接编辑表单。 --- # 性能 (https://talivia.com/zh-CN/docs/performance) 性能采集会将网页核心性能指标记录为分析事件。如需将页面速度与访客、会话和收入联系起来，请启用此功能。 ## 启用网页核心性能指标 [#启用网页核心性能指标] ```html ``` Talivia 可以采集： * `LCP` 最大内容绘制。 * `INP` 交互到下一次绘制。 * `CLS` 累计布局偏移。 * `FCP` 首次内容绘制。 * `TTFB` 首字节时间。 ## 报表 [#报表] 打开**性能**，查看加载缓慢或存在交互问题的页面。使用筛选条件分析单个路径、浏览器、国家或地区以及流量来源。 ## 实用工作流程 [#实用工作流程] 先检查能够带来收入的页面。定价页或结账页速度缓慢，通常比低购买意向的内容页更值得优先处理。 --- # 追踪像素 (https://talivia.com/zh-CN/docs/pixels) 追踪像素是一种轻量级网址，每次被请求时都会记录一个事件。无法安装完整 JavaScript 追踪器时，它尤其有用。 在**追踪像素**中创建像素，然后复制生成的网址。 ```txt https://talivia.com/p/abc123xyz ``` ## 常见用途 [#常见用途] * 在允许加载图片的邮件中追踪打开情况。 * 追踪轻量级推广曝光。 * 嵌入第三方页面的资源。 ## 限制 [#限制] 像素请求不具备与 JavaScript 追踪器相同的浏览器上下文。您仍能看到从请求中推断出的国家或地区、用户代理和时间戳等信息，但无法获得完整的客户端路由行为。 --- # 收入 (https://talivia.com/zh-CN/docs/revenue) 收入归因能够显示哪些会话、来源、页面、推广活动和搜索词带来了收入。设置页面用于连接付款账户，各服务商指南则说明不同结账方式所需的具体实现。 ## 选择收入来源 [#选择收入来源] | 来源 | 适用情况 | 配置指南 | | ------------- | ------------------------- | --------------------------------------------------------- | | Stripe | 通过 Stripe 处理结账、付款链接、账单或订阅 | [Stripe](https://talivia.com/zh-CN/docs/revenue-guides/stripe) | | Yolfi | 通过 Yolfi 处理付款和订阅 | [Yolfi](https://talivia.com/zh-CN/docs/revenue-guides/yolfi) | | Dodo Payments | 使用 Dodo 付款链接或结账会话 | [Dodo Payments](https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments) | | 手动付款接口 | 后端通过自定义或暂不支持的付款系统确认收入 | [手动付款接口](https://talivia.com/zh-CN/docs/revenue-guides/manual) | ## 配置分为哪些步骤 [#配置分为哪些步骤] 1. 在**网站设置 → 付款**中选择服务商并连接其接口密钥。 2. 在最后的**将付款与流量关联**步骤中打开相应的服务商指南。 3. 按照与您的实现一致的结账路径操作，并完成一笔测试付款。 4. 确认 Talivia 中的付款已经关联来源和会话。 连接服务商后，Talivia 可以导入和接收收入。会话元数据或已追踪的返回网址则提供归因信号，将收入与访问关联起来。 连接状态与归因状态需要分别检查。即使服务商已经成功连接，如果结账流程没有提供 Talivia 会话信号，付款仍可能无法归因。 ## 退款 [#退款] 退款会在图表中显示为冲减收入。Talivia 会保留原始付款上下文，方便查看原本计入的收入和实际退款金额。 截图占位：包含付款和退款柱形的收入图表。 --- # Dodo Payments (https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments) 网站上的付款链接 使用普通 Dodo 链接或链接按钮；Talivia 会自动处理归因。 结账会话 后端创建 Dodo 结账时添加一个 Talivia 会话值。 共享付款链接 付款仍会记录，但未访问您网站的买家可能无法归因。 测试与排查 Dodo Payments 检查接口环境、托管网络回调、结账元数据和退款。 --- # Dodo 结账会话 (https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments/checkout-session) 后端创建 Dodo 结账会话时使用此方案。Dodo 浮层结账和内嵌结账也从结账会话开始，因此同样适用。 在**网站设置 → 收入 → Dodo Payments**中连接账户，然后把当前 Talivia 会话放入结账元数据。 ## 将会话加入结账元数据 [#将会话加入结账元数据] 在后端读取 Talivia 会话 Cookie，并将它合并到现有 Dodo 调用的 `metadata` 对象中。 ```javascript title="创建 Dodo 结账会话" const taliviaSessionId = request.cookies.get('talivia_session_id')?.value; const checkout = await dodo.checkoutSessions.create({ product_cart, return_url: 'https://your-site.com/thanks', metadata: { // Keep your existing metadata fields here. ...(taliviaSessionId && { talivia_session_id: taliviaSessionId }), }, }); ``` `metadata` 是 Dodo 的标准元数据对象。请保留已有字段，只新增 `talivia_session_id`。Talivia 会从已验证的付款事件中读取该值并完成归因。 ## 结账接口位于其他来源 [#结账接口位于其他来源] 如果浏览器代码调用其他来源的结账接口，请在请求中包含不透明的会话值： ```javascript title="浏览器移交结账" const sessionId = window.talivia.getSessionId(); await fetch('https://api.your-site.com/create-checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId }), }); ``` 照常验证请求。后端创建结账会话时，将收到的值放入 `metadata.talivia_session_id`。会话编号是归因标识符，不是身份验证凭据。 服务商端选项请参阅 [Dodo 结账会话](https://docs.dodopayments.com/developer-resources/checkout-session)。 无需手动配置网络回调。 连接服务商时，Talivia 会配置并验证 Dodo 网络回调。 --- # 网站上的 Dodo 付款链接 (https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments/payment-link-on-your-site) 客户从您的网站打开 Dodo 付款链接时使用此方案。请先在**网站设置 → 收入 → Dodo Payments**中连接账户。 ## 将链接加入已追踪页面 [#将链接加入已追踪页面] 在普通 `` 链接或链接按钮中使用从 Dodo 复制的完整付款链接。无需编写 Talivia 专用结账代码。 ```html title="Dodo 付款链接" Buy now ``` Talivia 追踪器会在打开结账前添加当前会话，并保留链接中已有的参数。Dodo 报告付款成功后，Talivia 会将它与来源访问匹配。 只有客户在运行 Talivia 追踪器的页面上点击普通 Dodo 链接时才会自动归因。如果应用通过 Dodo 接口创建结账会话，请改用[结账会话指南](https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments/checkout-session)。 服务商端链接配置请参阅 [Dodo 付款链接](https://docs.dodopayments.com/developer-resources/integration-guide)。 无需手动配置网络回调。 在网站设置中连接 Dodo Payments 后，Talivia 会配置网络回调并导入可用的收入历史。 --- # 共享 Dodo 付款链接 (https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments/shared-payment-link) 直接共享 Dodo 付款链接无需结账代码。请在**网站设置 → 收入**中连接 Dodo Payments，让 Talivia 能够接收并记录成功付款。 ## 付款何时无法归因 [#付款何时无法归因] 如果买家通过邮件、聊天、社交帖子、交易市场或二维码直接打开 Dodo，且没有访问您的网站，就不存在可关联的 Talivia 网站会话。付款仍会记录，但可能显示为**未归因**。 这是预期行为：服务商网络回调能够证明付款发生，但无法追溯创建之前不存在的网站访问。 ## 推荐流程 [#推荐流程] 为了可靠归因，请分享您网站上的落地页，而不是原始 Dodo 结账网址。在该已追踪页面上放置付款链接： ```html title="已追踪落地页" Buy now ``` 访客点击购买时，Talivia 便可附加当前会话。完整行为请继续阅读[网站上的付款链接](https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments/payment-link-on-your-site)。 无需手动配置网络回调。 直接付款和已归因的 Dodo 付款使用网站设置中同一个服务商连接。 --- # 测试与排查 Dodo Payments (https://talivia.com/zh-CN/docs/revenue-guides/dodo-payments/testing-and-troubleshooting) 先使用[通用付款测试配置](https://talivia.com/zh-CN/docs/revenue-guides/testing-payment-providers)分离测试与生产收入，再完成以下 Dodo 专项检查。 ## 连接测试账户 [#连接测试账户] 在 Dodo 测试环境中创建拥有写入权限的接口密钥，并连接到测试 Talivia 网站。Talivia 会识别密钥属于测试环境还是正式环境，然后调用相应接口验证商户、导入可用历史并创建网络回调。 Talivia 中没有 Dodo 环境选择器。如果当前 Dodo 密钥没有环境前缀，Talivia 会在各服务商环境中验证，并保存验证成功的连接。 ## 最小测试矩阵 [#最小测试矩阵] | 场景 | Talivia 预期结果 | | ------------ | ------------------------------------- | | 从已追踪页面点击付款链接 | 付款匹配到来源会话 | | 通过接口创建结账会话 | 通过 `metadata.talivia_session_id` 匹配付款 | | 浮层或内嵌结账 | 与其底层结账会话结果相同 | | 未访问网站而直接打开链接 | 付款记录为**未归因** | | 全额或部分退款 | 保留原始付款并减少净收入 | | 重复网络回调 | 不重复创建付款或退款 | ## 连接失败 [#连接失败] * \*\*两个环境都拒绝密钥：\*\*从 Dodo 复制新接口密钥后重试。 * \*\*禁止创建网络回调：\*\*为密钥启用写入权限。 * \*\*找不到商户：\*\*确认密钥所属 Dodo 账户有可用的商户或品牌。 重新连接会更新 Talivia 网络回调网址对应的托管端点。账户或环境改变时，Talivia 会导入新历史并删除之前的托管端点。 ## 没有出现付款 [#没有出现付款] 在 Dodo 网络回调设置中，确认 Talivia 端点已启用，并且 `payment.succeeded` 投递返回成功响应。退款更新需要 `refund.succeeded`。 若缺少投递，请重新连接 Dodo，让 Talivia 修复网络回调并取回签名密钥。若投递被拒绝，请确认事件来自连接密钥所在的同一 Dodo 环境。 ## 付款未归因 [#付款未归因] * \*\*付款链接：\*\*通过运行 Talivia 追踪器的页面上的普通链接打开。 * \*\*结账会话、浮层或内嵌结账：\*\*后端创建结账会话时，将当前会话加入 `metadata.talivia_session_id`。 * \*\*共享原始链接：\*\*买家从未访问已追踪网站时，付款未归因属于预期结果。 请勿将 Talivia 会话编号用于身份验证。它只是一个不透明的归因值。 --- # LemonSqueezy (https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy) 结账链接 在已追踪网站上使用托管结账或标准 Lemon.js 浮层链接。 结账接口 在后端创建自定义结账，并明确传入 Talivia 会话。 返回网址备用方案 原始结账无法添加元数据时，通过返回页面匹配订单。 订阅与续费 在循环付款和生命周期变化中保留首次结账归因。 测试与排查 LemonSqueezy 验证密钥模式、托管网络回调、自定义数据、订阅和退款。 --- # LemonSqueezy 结账接口 (https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-api) 后端调用 `POST /v1/checkouts` 并把生成的结账网址返回浏览器时，请使用此流程。 ## 将会话发送给后端 [#将会话发送给后端] 在已追踪页面上读取当前会话，并放入自己的结账请求： ```javascript title="从浏览器开始结账" const sessionId = window.talivia.getSessionId(); const response = await fetch('/api/create-checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId }), }); const { checkoutUrl } = await response.json(); window.location.assign(checkoutUrl); ``` 会话编号只能作为归因上下文。客户、商品、价格和权限仍须由后端独立验证。 ## 添加自定义结账数据 [#添加自定义结账数据] 将收到的值合并到 LemonSqueezy 请求的 `attributes.checkout_data.custom`： ```javascript title="创建 LemonSqueezy 结账" const checkout = await fetch('https://api.lemonsqueezy.com/v1/checkouts', { method: 'POST', headers: { Accept: 'application/vnd.api+json', 'Content-Type': 'application/vnd.api+json', Authorization: `Bearer ${process.env.LEMONSQUEEZY_API_KEY}`, }, body: JSON.stringify({ data: { type: 'checkouts', attributes: { checkout_data: { custom: { talivia_session_id: sessionId } }, }, relationships: { store: { data: { type: 'stores', id: process.env.LEMONSQUEEZY_STORE_ID } }, variant: { data: { type: 'variants', id: variantId } }, }, }, }), }).then(response => response.json()); return Response.json({ checkoutUrl: checkout.data.attributes.url }); ``` LemonSqueezy 会把自定义结账数据复制到带签名网络回调的 `meta.custom_data`。托管自定义结账和通过程序打开的浮层都适用。 请将 LemonSqueezy 接口密钥保存在服务器，并保留应用已经发送的其他自定义字段。 --- # LemonSqueezy 结账链接 (https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-links) 客户在安装了 Talivia 追踪器的页面上点击可重复使用的 LemonSqueezy 结账链接时，请使用此流程。 ## 将链接加入网站 [#将链接加入网站] 请使用包含 `/checkout/buy/` 的原始分享网址，不要复制结账打开后生成的一次性购物车网址。 ```html title="托管的 LemonSqueezy 结账" Buy now ``` Talivia 会添加当前会话，同时保留折扣、数量和其他已有查询参数： ```text checkout[custom][talivia_session_id]=s_... ``` LemonSqueezy 会在订单和订阅网络回调事件中，以 `meta.custom_data.talivia_session_id` 返回该值。Talivia 用它把收入关联到来源访问。 ## 结账浮层 [#结账浮层] 普通结账链接作为 Lemon.js 浮层按钮时，同样会自动处理： ```html title="Lemon.js 浮层链接" Buy now ``` 链接仍须是已追踪页面上的标准锚点。如果应用创建自定义结账，或使用在其他位置生成的网址调用 `LemonSqueezy.Url.Open()`，请继续阅读[结账接口](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-api)。 无需手动配置网络回调。 在网站设置中连接 LemonSqueezy 会创建带签名的订单、订阅和退款网络回调。 --- # LemonSqueezy 返回网址备用方案 (https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/return-url) 直接会话元数据是最可靠的归因方式。只有无法修改结账链接或接口请求时，才应使用返回网址。 ## 将订单编号加入返回链接 [#将订单编号加入返回链接] 在 LemonSqueezy 商品设置中，将确认弹窗按钮链接设为已追踪页面，并包含支持的 `order_id` 变量： ```text title="确认按钮网址" https://your-site.com/thanks?order_id=[order_id] ``` 付款后，LemonSqueezy 会用真实订单编号替换 `[order_id]`。客户打开该页面时，Talivia 追踪器会记录订单引用，并与已验证的 `order_created` 网络回调匹配。 ## 返回归因的限制 [#返回归因的限制] * 返回页面必须安装追踪器。 * 客户必须点击确认按钮，并在同一浏览器中返回。 * 如果客户在访问您网站之前就打开共享结账，Talivia 仍可记录付款，但无法恢复更早的获客会话。 * 不要依赖返回页面履行订单；带签名网络回调才是付款事实来源。 已追踪网站上呈现的链接请使用[结账链接](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-links)，服务器创建的结账请使用[结账接口](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-api)。 --- # LemonSqueezy 订阅与续费 (https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/subscriptions-and-renewals) 首次订阅结账应使用与单次订单相同的 Talivia 会话字段。标准[结账链接](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-links)可自动添加，也可通过[结账接口](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-api)设置 `checkout_data.custom.talivia_session_id`。 LemonSqueezy 会在首次订单和订阅网络回调中包含该自定义数据。Talivia 会保存 LemonSqueezy 客户与订阅关系，因此后续续费即使没有新的浏览器结账也能保持关联。 ## Talivia 维护的事件 [#talivia-维护的事件] 托管网络回调会处理： * 订阅创建与更新； * 取消、恢复、暂停、解除暂停和到期； * 成功、失败和恢复的订阅付款； * 订阅付款退款。 成功的续费账单会成为新的收入付款。付款失败只更新订阅状态，不创建已付收入；退款会减少原始付款的净收入。 ## 保持客户关系稳定 [#保持客户关系稳定] 请勿在每次续费或套餐变更时创建新的 LemonSqueezy 客户。保持服务商客户编号和订阅编号稳定，Talivia 才能复用首次结账建立的归因。 续费未归因时，请先确认首次结账包含 `meta.custom_data.talivia_session_id`，再确认后续事件使用同一 LemonSqueezy 客户和订阅。 --- # 测试与排查 LemonSqueezy (https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/testing-and-troubleshooting) 先用[通用付款测试配置](https://talivia.com/zh-CN/docs/revenue-guides/testing-payment-providers)分离测试与生产收入，再完成以下 LemonSqueezy 检查。 ## 连接测试模式 [#连接测试模式] 1. 在测试模式下创建或选择 LemonSqueezy 商店。 2. LemonSqueezy 处于测试模式时创建接口密钥。 3. 将该商店编号和接口密钥连接到测试 Talivia 网站。 Talivia 会检测接口密钥模式，并使用匹配的 `test_mode` 值创建网络回调；无需另选环境。 ## 最小测试矩阵 [#最小测试矩阵] | 场景 | Talivia 预期结果 | | ------- | -------------- | | 单次订单 | 一笔包含订单金额和币种的付款 | | 注册订阅 | 首次付款及一个有效订阅 | | 订阅续费 | 一笔关联到同一客户的新付款 | | 续费失败或恢复 | 订阅状态改变且不重复计算收入 | | 全额或部分退款 | 保留原始付款并减少净收入 | | 重复网络回调 | 不重复创建付款或订阅 | ## 连接失败 [#连接失败] * 确认接口密钥能够读取输入的商店编号。 * 确认两个值来自同一 LemonSqueezy 环境。 * LemonSqueezy 返回 `401` 或 `403` 时创建新接口密钥。 * 更换密钥后重新连接；Talivia 会创建新的签名网络回调并删除之前的托管端点。 ## 没有出现付款 [#没有出现付款] 打开 LemonSqueezy 的**设置 → 网络回调**，找到所连接商店的 Talivia 端点。确认投递成功，而且事件属于 Talivia 支持的类型，例如 `order_created`、`subscription_payment_success`、`order_refunded` 或 `subscription_payment_refunded`。 若端点缺失或 `test_mode` 错误，请用目标环境的接口密钥从 Talivia 重新连接。 ## 付款未归因 [#付款未归因] * \*\*标准链接或浮层：\*\*按[结账链接](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-links)配置，并确认结账从已追踪页面开始。 * \*\*服务器创建的结账：\*\*按[结账接口](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/checkout-api)配置，并确认包含 `checkout_data.custom.talivia_session_id`。 * \*\*无法添加元数据：\*\*配置[返回网址备用方案](https://talivia.com/zh-CN/docs/revenue-guides/lemonsqueezy/return-url)。 前两种流程可在网络回调中检查 `meta.custom_data.talivia_session_id` 是否包含会话。 --- # 手动付款接口 (https://talivia.com/zh-CN/docs/revenue-guides/manual) 如果收入来自自定义结账、银行转账、数字货币处理商、应用商店、账单系统或 Talivia 尚未直接连接的其他服务商，请使用手动付款接口。 ## 创建接口密钥 [#创建接口密钥] 打开**网站设置 → 接口密钥**并生成密钥。Talivia 会为当前网站创建密钥。 密钥只显示一次，请立即复制。只能将它保存在后端，切勿暴露在浏览器代码中。 ## 发送付款 [#发送付款] 后端确认已经收到款项后，再把付款事件发送给 Talivia。 结账前，将 `window.talivia.getSessionId()` 发送给后端，并作为 `sessionId` 与订单一起保存。 ```javascript title="记录已确认付款" await fetch('https://talivia.com/api/payments/manual', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-talivia-api-key': process.env.TALIVIA_API_KEY, }, body: JSON.stringify({ websiteId: 'YOUR_WEBSITE_ID', transactionId: 'order_123', amount: 49, currency: 'USD', providerName: 'manual', providerPaymentId: 'payment_123', providerCustomerId: 'customer_123', sessionId: order.sessionId, }), }); ``` 请使用稳定的编号。 `transactionId` 应是系统中该笔付款的唯一编号。请求重试时请重复使用同一个编号。 ## 支持的归因字段 [#支持的归因字段] 请尽可能发送会话字段： * `sessionId` * `providerCustomerId` * `externalCustomerId` * `email` * `emailHash` Talivia 使用 `sessionId` 将付款关联到准确的访客路径。首次付款匹配成功后，客户字段可以进一步关联后续续费。 ## 验证 [#验证] 1. 从后端发送一笔测试付款。 2. 打开该网站的 Talivia 付款列表。 3. 确认金额、币种、服务商名称和交易编号。 4. 打开会话详情，确认匹配会话中显示了消费金额。 --- # Polar (https://talivia.com/zh-CN/docs/revenue-guides/polar) 结账接口 在后端创建结账，并直接附加 Talivia 会话。 结账链接 使用无需代码的 Polar 链接，在买家返回时匹配付款。 内嵌结账 在网站中打开 Polar，同时保留基于返回页面的归因。 订阅与续费 在循环订单和生命周期变化中保留原始客户身份。 其他方式 通过稳定的 Polar 客户身份归因自定义集成。 测试与排查 Polar 检查令牌权限、测试结账、归因、订阅和退款。 --- # Polar 结账接口 (https://talivia.com/zh-CN/docs/revenue-guides/polar/checkout-api) 这是最可靠的 Polar 集成方式。Talivia 会在带签名的 `order.paid` 网络回调中收到同一会话编号，无需依赖返回访问即可归因订单。 ## 将 Talivia 会话发送给后端 [#将-talivia-会话发送给后端] ```javascript title="浏览器移交结账" const sessionId = window.talivia.getSessionId(); const response = await fetch('/api/create-polar-checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId }), }); const { url } = await response.json(); window.location.assign(url); ``` 会话编号是归因标识符，不是身份验证凭据。请照常在后端验证商品和已登录用户。 ## 创建结账时添加元数据 [#创建结账时添加元数据] 将 Polar 访问令牌保存在服务器。Polar 会把结账元数据复制到生成的订单和订阅，因此一个字段即可覆盖单次和循环产品。 ```javascript title="创建 Polar 结账会话" import { Polar } from '@polar-sh/sdk'; const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN }); const checkout = await polar.checkouts.create({ products: [process.env.POLAR_PRODUCT_ID], successUrl: 'https://your-site.com/thanks?checkout_id={CHECKOUT_ID}', returnUrl: 'https://your-site.com/pricing', externalCustomerId: user.id, customerEmail: user.email, metadata: { talivia_session_id: sessionId }, }); return Response.json({ url: checkout.url }); ``` `externalCustomerId` 应是应用中稳定的编号，可为未来续费提供第二个匹配信号。请在成功网址中保留 `checkout_id={CHECKOUT_ID}`，作为备用和排查信号。 --- # Polar 结账链接 (https://talivia.com/zh-CN/docs/revenue-guides/polar/checkout-links) 结账链接无法让服务器为每位买家附加新的 Talivia 元数据。请使用 Polar 的成功网址占位符，让 Talivia 在买家返回时把完成的结账关联到浏览器会话。 ## 配置链接 [#配置链接] 1. 在 Polar 中创建或编辑结账链接。 2. 将成功网址设为网站上的已追踪页面。 3. 加入准确的 `checkout_id={CHECKOUT_ID}` 查询参数。 ```text title="成功网址" https://your-site.com/thanks?checkout_id={CHECKOUT_ID} ``` 将链接放在安装了 Talivia 追踪器的页面上。 ```html title="结账链接" Buy now ``` 付款后，Polar 网络回调会记录订单；返回页面将网址中的结账编号发送给 Talivia，提供会话侧匹配信号。 共享链接存在自然限制。 如果买家从邮件或社交媒体打开链接，且从未访问已追踪网站，Talivia 会记录收入但无法凭空产生流量来源。除非客户身份提供其他匹配，否则付款会保持未归因。 已登录产品还应使用 Polar 中相同的应用客户编号调用 `identify`。请参阅[其他方式](https://talivia.com/zh-CN/docs/revenue-guides/polar/other-methods)。 --- # Polar 内嵌结账 (https://talivia.com/zh-CN/docs/revenue-guides/polar/embedded-checkout) Polar 内嵌结账是在内嵌框架中显示的结账链接。归因规则与普通链接相同：成功网址须位于已追踪域名，并包含 `checkout_id={CHECKOUT_ID}`。 ## 添加结账触发器 [#添加结账触发器] ```html title="内嵌结账" Buy now ``` 使用内嵌结账前，先配置底层结账链接的成功网址： ```text title="成功网址" https://your-site.com/thanks?checkout_id={CHECKOUT_ID} ``` ## React 或程序化内嵌 [#react-或程序化内嵌] ```javascript title="通过程序打开结账" import { PolarEmbedCheckout } from '@polar-sh/checkout/embed'; await PolarEmbedCheckout.create('https://buy.polar.sh/polar_cl_YOUR_LINK', 'dark'); ``` 不要把客户端 `success` 事件当作收入事实来源。Talivia 从 Polar 带签名的 `order.paid` 网络回调记录收入，浏览器返回只用于归因。 如果通过接口创建内嵌结账会话，请将 `embedOrigin` 设为网站来源，并使用[结账接口元数据](https://talivia.com/zh-CN/docs/revenue-guides/polar/checkout-api)获得最可靠匹配。 --- # Polar 的其他归因方式 (https://talivia.com/zh-CN/docs/revenue-guides/polar/other-methods) 部分集成通过其他计费层创建客户或订单，无法传入 `talivia_session_id`。此时，请将访客关联到 Polar 网络回调中出现的同一客户身份。 ## 使用稳定的外部客户编号 [#使用稳定的外部客户编号] 集成支持时，请把 Polar 的 `external_customer_id` 设为您自己的不可变用户编号，并用该值识别已登录访客。 ```javascript title="识别应用客户" window.talivia.identify(user.id, { email: user.email, externalCustomerId: user.id, providerName: 'polar', }); ``` 如果后端已知 Polar 客户 UUID，也请一并提供。 ```javascript title="识别 Polar 客户" window.talivia.identify(user.id, { email: user.email, externalCustomerId: user.id, providerName: 'polar', polarCustomerId: 'YOUR_POLAR_CUSTOMER_ID', }); ``` 能够控制结账创建时，请优先使用[结账接口](https://talivia.com/zh-CN/docs/revenue-guides/polar/checkout-api)。直接会话元数据能够确定匹配；客户身份是结账的备用信号，也是续费的主要信号。 如果会话元数据、结账返回、外部客户编号、Polar 客户编号和已验证的匹配电子邮箱均不可用，Talivia 仍会记录订单，但显示为未归因。 --- # Polar 订阅与续费 (https://talivia.com/zh-CN/docs/revenue-guides/polar/subscriptions-and-renewals) Talivia 会监听 Polar 订阅生命周期事件，并从 `order.paid` 记录已付款续费订单。首次结账应同时包含 Talivia 会话编号和稳定的应用客户编号。 ```javascript title="创建循环结账" const checkout = await polar.checkouts.create({ products: [process.env.POLAR_RECURRING_PRODUCT_ID], successUrl: 'https://your-site.com/thanks?checkout_id={CHECKOUT_ID}', externalCustomerId: user.id, customerEmail: user.email, metadata: { talivia_session_id: sessionId }, }); ``` Polar 会把结账元数据复制到创建的订阅。Talivia 保存订阅状态，并在没有新浏览器会话的后续订单中复用客户身份。 ## 识别已登录客户 [#识别已登录客户] 登录后调用 `identify`；获得 Polar 客户编号后再调用一次。 ```javascript title="关联 Polar 客户" window.talivia.identify(user.id, { email: user.email, externalCustomerId: user.id, providerName: 'polar', polarCustomerId: polarCustomer.id, }); ``` 结账时设置相同值后，外部编号通常已经足够；增加 Polar 客户编号可提升匹配韧性。 ## Talivia 导入哪些内容 [#talivia-导入哪些内容] * 首次已付款订单和之后的已付款续费； * 累计的全额或部分退款； * 订阅创建和状态变化； * 首次连接回填时的有效订阅上下文。 没有已付款订单的试用只保存为订阅状态，不计为收入。 --- # 测试与排查 Polar (https://talivia.com/zh-CN/docs/revenue-guides/polar/testing-and-troubleshooting) 先完成[通用付款测试配置](https://talivia.com/zh-CN/docs/revenue-guides/testing-payment-providers)，再执行以下 Polar 专项连接与归因检查。 ## 连接检查清单 [#连接检查清单] 在 Polar 中为正确的组织创建组织访问令牌，并授予以下权限： * 读取结账； * 读取订单； * 读取组织； * 读取商品； * 读取订阅； * 写入网络回调。 在**网站设置 → 收入 → Polar**中粘贴令牌并选择**连接 Polar**。Talivia 会检测令牌所属组织和生产/测试环境，验证每项权限，创建签名网络回调，导入过去 30 天的订单并同步订阅状态。 无需复制网络回调密钥，也无需创建 OAuth 应用。 ## 端到端测试 [#端到端测试] 1. 创建单独的 Talivia 网站，并连接 Polar 测试组织。 2. 从已追踪浏览器会话打开结账。 3. 使用 Polar 测试付款流程完成订单。 4. 确认付款以服务商 **Polar** 出现在 Talivia 中。 5. 打开付款，核对会话、来源、入口页面和金额。 6. 在 Polar 中创建退款，确认同一付款的退款金额已更新。 ## 付款未归因 [#付款未归因] 对于结账接口，检查创建的结账，确认 `metadata.talivia_session_id` 等于 `window.talivia.getSessionId()` 返回的值。 对于结账链接和内嵌结账，确认 Polar 成功网址是已追踪页面，并包含： ```text checkout_id={CHECKOUT_ID} ``` 对于订阅或自定义流程，确认 Polar 客户的 `external_id` 与发送给 `window.talivia.identify` 的 `externalCustomerId` 相同。 ## 连接失败 [#连接失败] * \*\*找不到组织：\*\*确认令牌拥有组织读取权限，并且是组织访问令牌。 * \*\*权限错误：\*\*重新创建或更新令牌，授予清单中的全部权限。 * \*\*网络回调错误：\*\*确认已启用写入网络回调并重新连接；Talivia 会修复或重建端点。 * \*\*生产与测试：\*\*Talivia 会自动从令牌检测环境。请将测试和生产环境放在不同 Talivia 网站中，避免混合收入。 --- # Stripe (https://talivia.com/zh-CN/docs/revenue-guides/stripe) 结账会话 托管或内嵌的 Stripe 结账，适合大多数新集成。 付款链接 通过 buy.stripe.com 链接实现无需代码的结账。 付款意图 直接创建付款意图的自定义结账。 订阅与账单 循环套餐、续费和账单付款。 其他方式 自定义计费层、第三方处理商或尚未支持的 Stripe 对象。 测试与排查 Stripe 验证事件、归因、订阅、退款和付款链接。 --- # Stripe 结账会话 (https://talivia.com/zh-CN/docs/revenue-guides/stripe/checkout-sessions) Stripe 托管结账以及用结账会话接口构建的内嵌结账都适用此集成。 ## 将 Talivia 会话传给后端 [#将-talivia-会话传给后端] 如果结账请求从浏览器代码开始，请包含当前不透明的会话编号。 ```javascript title="浏览器移交结账" const sessionId = window.talivia.getSessionId(); const response = await fetch('/api/create-checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId }), }); const { url } = await response.json(); window.location.assign(url); ``` 如果结账与 Talivia 追踪器位于同一网站，后端也可以读取第一方 Cookie `talivia_session_id`。请照常验证请求输入；会话编号是归因标识符，不是身份验证凭据。 ## 单次付款 [#单次付款] 同时为结账会话及其底层付款意图设置元数据。无论 Stripe 先送达哪一个成功事件，都能保留归因。 ```javascript title="创建单次付款结账会话" const session = await stripe.checkout.sessions.create({ mode: 'payment', line_items: [{ price: 'price_123', quantity: 1 }], success_url: 'https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}', cancel_url: 'https://your-site.com/pricing', metadata: { talivia_session_id: sessionId }, payment_intent_data: { metadata: { talivia_session_id: sessionId } }, }); ``` 顶层 `metadata` 出现在 `checkout.session.completed` 上；`payment_intent_data.metadata` 会复制到付款意图，并出现在 `payment_intent.succeeded` 上。 ## 订阅结账 [#订阅结账] 循环套餐应把会话编号复制到订阅，让续费和生命周期事件保留原始客户上下文。 ```javascript title="创建订阅结账会话" const session = await stripe.checkout.sessions.create({ mode: 'subscription', line_items: [{ price: 'price_monthly', quantity: 1 }], success_url: 'https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}', cancel_url: 'https://your-site.com/pricing', metadata: { talivia_session_id: sessionId }, subscription_data: { metadata: { talivia_session_id: sessionId } }, }); ``` 续费、失败账单和客户身份请继续阅读[订阅与账单](https://talivia.com/zh-CN/docs/revenue-guides/stripe/subscriptions-and-invoices)。 ## 延迟付款方式 [#延迟付款方式] 银行扣款、凭证及部分本地付款方式可能在确认到账前就完成结账。Talivia 不会将尚未付款的已完成会话记为收入，而会等待 Stripe 异步成功事件，并只导入 `payment_status` 为 `paid` 的会话。 ## 返回网址备用信号 [#返回网址备用信号] 即使已经添加元数据，也请在成功网址中保留 `{CHECKOUT_SESSION_ID}`。返回访问能提供第二个匹配信号，也有助于排查元数据缺失。 --- # Stripe 的其他归因方式 (https://talivia.com/zh-CN/docs/revenue-guides/stripe/other-methods) 请选择能够为 Talivia 提供服务器验证付款的最小范围集成。 ## Stripe 对象仍在已连接账户中 [#stripe-对象仍在已连接账户中] 如果第三方结账在连接到 Talivia 的同一个 Stripe 账户中创建付款意图，请使用[付款意图](https://talivia.com/zh-CN/docs/revenue-guides/stripe/payment-intents)。第三方允许提供付款意图元数据时，请附加 `talivia_session_id`。 如果无法提供元数据，请使用 Stripe 付款中相同的电子邮箱或客户编号识别已登录客户： ```javascript title="关联客户身份" window.talivia.identify('user_123', { email: currentUser.email, stripeCustomerId: currentUser.stripeCustomerId, }); ``` 这只会关联身份，不会在浏览器中创建或确认收入；Stripe 带签名网络回调仍是付款事实来源。 ## 处理商隐藏 Stripe 付款对象 [#处理商隐藏-stripe-付款对象] 后端确认付款后使用[手动付款接口](https://talivia.com/zh-CN/docs/revenue-guides/manual)。发送与订单一起保存的 Talivia 会话和稳定的交易编号。 ```javascript title="记录第三方确认的付款" await fetch('https://talivia.com/api/payments/manual', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-talivia-api-key': process.env.TALIVIA_API_KEY, }, body: JSON.stringify({ websiteId: 'YOUR_WEBSITE_ID', providerName: 'your-billing-provider', transactionId: payment.id, providerCustomerId: payment.customerId, email: payment.customerEmail, amount: payment.amount, currency: payment.currency, sessionId: order.taliviaSessionId, }), }); ``` ## 为什么没有浏览器付款命令 [#为什么没有浏览器付款命令] 公开 `payment` 事件可以被重放或伪造，因此 Talivia 将两项职责分开： * 浏览器追踪和 `identify` 提供归因上下文； * 带签名 Stripe 网络回调或经过身份验证的后端接口确认收入。 这样既能保持金额和付款状态可信，也能支持自定义计费流程。 --- # Stripe 付款意图 (https://talivia.com/zh-CN/docs/revenue-guides/stripe/payment-intents) 后端直接调用 `stripe.paymentIntents.create` 时使用本指南。对于大多数新网页集成，Stripe 推荐通过结账会话使用付款元素，因为它能代为管理更多结账行为。 ## 将会话带入付款创建流程 [#将会话带入付款创建流程] 把 Talivia 会话编号发送到创建付款意图的后端。切勿在浏览器代码中用 Stripe 密钥创建付款意图。 ```javascript title="浏览器移交" const sessionId = window.talivia.getSessionId(); const response = await fetch('/api/create-payment-intent', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId }), }); const { clientSecret } = await response.json(); ``` 在服务器创建付款意图，并把会话直接附加到元数据。 ```javascript title="创建付款意图" const paymentIntent = await stripe.paymentIntents.create({ amount: 2500, currency: 'usd', automatic_payment_methods: { enabled: true }, customer: stripeCustomerId, receipt_email: customerEmail, metadata: { talivia_session_id: sessionId }, }); return Response.json({ clientSecret: paymentIntent.client_secret }); ``` Talivia 监听 `payment_intent.succeeded`、记录 `amount_received`，并按付款意图编号去重。与 Stripe 账单关联的付款意图留给账单事件处理，以免丢失续费和订阅上下文。 ## 移动端与网页转应用结账 [#移动端与网页转应用结账] 请通过经过身份验证的结账移交或深层链接状态传递原始网页会话编号，并与后端订单一起保存。移动应用不需要 Talivia 浏览器追踪器；后端创建付款意图时只需附加之前捕获的不透明编号。 ## 身份备用信号 [#身份备用信号] 提供稳定的 Stripe 客户和收据电子邮箱，有助于匹配后续付款。登录或注册后，请在已追踪网站上关联身份： ```javascript title="识别 Stripe 客户" window.talivia.identify('user_123', { email: 'buyer@example.com', stripeCustomerId: 'cus_123', }); ``` 身份是备用信号和续费桥梁；元数据仍是把首次付款归因到准确结账会话的最可靠信号。 --- # Stripe 付款链接 (https://talivia.com/zh-CN/docs/revenue-guides/stripe/payment-links) 付款链接无需自定义结账接口。Talivia 支持直接链接信号和返回网址备用方案。 ## 通过链接直接归因 [#通过链接直接归因] Talivia 追踪器发现标准 `https://buy.stripe.com/...` 锚点时，会在跳转前把当前会话作为 Stripe 的 `client_reference_id` 添加。 ```html title="标准 Stripe 付款链接" Buy now ``` Stripe 会在生成的结账会话中包含该引用；付款网络回调到达时，Talivia 会使用它。 Talivia 绝不会覆盖已有 `client_reference_id`。如果产品已经将该参数用于购物车或客户编号，请配置下方的返回网址作为归因信号。 自动添加参数有适用边界。 它适用于 `buy.stripe.com` 上的普通链接。自定义 Stripe 域名或通过 `window.location` 直接跳转时，请使用返回网址或自行集成结账会话。 ## 配置返回网址 [#配置返回网址] 1. 在 Stripe 控制台中打开付款链接。 2. 打开**付款后**。 3. 选择**将客户重定向到您的网站**。 4. 设置包含 Stripe 字面量占位符的网址： ```text title="付款链接重定向" https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID} ``` 目标页面须安装 Talivia 追踪器。Talivia 会检测结账会话编号、与已验证的 Stripe 网络回调匹配，并重新计算归因，即使网络回调先于浏览器返回也能处理。 结账和目标页面在同一浏览器打开时，返回方式效果最佳；直接使用 `client_reference_id` 的归因不依赖客户付款后返回。 --- # Stripe 订阅与账单 (https://talivia.com/zh-CN/docs/revenue-guides/stripe/subscriptions-and-invoices) 循环收入涉及两个归因问题：匹配最初的订阅注册，以及把之后的账单付款重新关联到同一客户路径。 ## 归因订阅注册 [#归因订阅注册] 结账创建订阅时，请同时在结账会话和后续订阅上设置 Talivia 会话。 ```javascript title="订阅元数据" const metadata = { talivia_session_id: sessionId }; await stripe.checkout.sessions.create({ mode: 'subscription', line_items: [{ price: 'price_monthly', quantity: 1 }], success_url: 'https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}', metadata, subscription_data: { metadata }, }); ``` Stripe 会在结账事件上提供结账元数据，在订阅事件上提供订阅元数据。订阅生成的账单会把元数据放在账单的订阅详情下。Talivia 同时读取当前的 `parent.subscription_details.metadata` 结构和较早的 `subscription_details.metadata` 结构。 ## 关联客户身份 [#关联客户身份] 客户登录、注册或进入已验证产品时调用 `identify`。 ```javascript title="将 Talivia 访客关联到 Stripe" window.talivia.identify('user_123', { email: currentUser.email, stripeCustomerId: currentUser.stripeCustomerId, }); ``` 续费没有新的浏览器结账会话时，Talivia 仍可通过 Stripe 客户完成归因。 ## Talivia 维护的事件 [#talivia-维护的事件] 托管 Stripe 网络回调会接收： * 成功和失败的账单付款； * 订阅创建、更新、取消、暂停、恢复、试用和待处理更新； * 成功退款和退款更新； * 争议创建、更新、结束和资金变动。 首次结账和账单事件可能以任意顺序到达。Talivia 会使用付款意图、结账会话、客户、金额和事件时间将它们合并为一笔付款，避免重复计算注册收入。 --- # 测试与排查 Stripe 归因 (https://talivia.com/zh-CN/docs/revenue-guides/stripe/testing-and-troubleshooting) 先完成[通用付款测试配置](https://talivia.com/zh-CN/docs/revenue-guides/testing-payment-providers)，再测试产品实际使用的 Stripe 结账路径，不要只发送通用网络回调样例。 ## 最小测试矩阵 [#最小测试矩阵] | 场景 | Talivia 预期结果 | | ------- | -------------------------------- | | 单次结账会话 | 一笔匹配到结账会话的已付付款 | | 直接付款意图 | 一笔以 `pi_...` 编号为键的付款 | | 付款链接 | 通过 `client_reference_id` 或返回网址匹配 | | 延迟付款方式 | 异步成功前不记录收入 | | 注册订阅 | 一笔首次付款和一个有效订阅 | | 订阅续费 | 一笔关联到原始客户的续费 | | 账单失败 | 订阅生命周期变化且不记录已付收入 | | 全额或部分退款 | 保留原始付款并减少净收入 | | 争议 | 将争议状态关联到原始付款 | | 重复或乱序事件 | 不重复付款 | ## 连接成功但没有出现付款 [#连接成功但没有出现付款] 检查 Stripe 控制台中网站端点的网络回调投递。相关成功事件必须是以下之一： * `checkout.session.completed` 或 `checkout.session.async_payment_succeeded`； * 直接付款意图的 `payment_intent.succeeded`； * 账单的 `invoice.paid` 或 `invoice.payment_succeeded`。 确认事件与 Talivia 中连接的受限密钥属于同一测试或正式模式。 ## 付款出现但未归因 [#付款出现但未归因] 检查流程使用的 Stripe 对象： * 结账会话：`metadata.talivia_session_id`； * 直接付款意图：`metadata.talivia_session_id`； * 订阅：`metadata.talivia_session_id`； * 付款链接结账会话：以 `s_` 开头、类似 Talivia 会话的 `client_reference_id`； * 返回页面：`?session_id=cs_...` 和正常运行的 Talivia 追踪器。 如果元数据缺失，请确认后端创建结账前 `window.talivia.getSessionId()` 已返回值。 ## 付款链接未添加参数 [#付款链接未添加参数] 自动添加参数要求普通锚点的主机名是 `buy.stripe.com`。Talivia 会保留已有 `client_reference_id`。自定义域名、程序化跳转或已有商户引用请配置带 `{CHECKOUT_SESSION_ID}` 的已追踪返回网址。 ## 续费未归因 [#续费未归因] 确认首次订阅付款已归因，后续账单使用同一 Stripe 客户。注册时添加 `subscription_data.metadata`，并在身份验证后使用 Stripe 客户编号调用 `window.talivia.identify`。 ## 重新连接 Stripe [#重新连接-stripe] 粘贴更新后的受限密钥时，Talivia 会协调现有 Stripe 网络回调网址和事件列表，而不是创建重复端点。如果原始连接早于托管端点编号功能，首次更新会创建并保存新的托管端点。 --- # 测试付款集成 (https://talivia.com/zh-CN/docs/revenue-guides/testing-payment-providers) Talivia 没有“正式/测试”切换开关。连接到网站的凭据决定 Talivia 调用哪个服务商环境，以及在哪个环境中配置托管网络回调。 请分开保存数据。 为预发布或测试付款使用一个 Talivia 网站，为生产环境使用另一个网站，避免测试收入进入生产转化和归因报表。 ## 使用两个网站 [#使用两个网站] | Talivia 网站 | 被追踪的环境 | 服务商凭据 | 应包含的数据 | | ---------- | ---------- | --------- | ------- | | 产品 — 测试环境 | 预发布网站或测试结账 | 测试环境密钥或令牌 | 仅测试付款 | | 产品 | 生产网站和结账 | 正式环境密钥或令牌 | 仅真实客户付款 | 服务商环境只是连接信息。Talivia 会验证并处理该连接送达的每个受支持事件；它不会根据另一套付款模式对收入进行分类、隐藏或筛选。 ## 通用测试流程 [#通用测试流程] 1. 创建测试用 Talivia 网站，并在预发布环境中安装追踪器。 2. 在**网站设置 → 收入**中连接服务商的测试凭据。 3. 从一个已追踪的浏览器会话中完成结账。 4. 确认付款金额、币种、状态和服务商。 5. 确认付款匹配到预期会话和流量来源。 6. 按服务商指南检查退款、订阅、投递日志和服务商特有错误。 流程验证完成后，将正式凭据连接到生产 Talivia 网站。保留测试网站，以便日后验证集成改动。 ## 各服务商检查指南 [#各服务商检查指南] Stripe 结账事件、付款链接、账单、争议和退款。 Dodo Payments 环境检测、网络回调投递、结账元数据和退款。 LemonSqueezy 密钥模式、网络回调事件、自定义结账数据和订阅。 Polar 令牌权限、测试结账、归因和退款。 Yolfi 事件路由、签名、元数据和订阅更新。 手动付款接口 稳定的交易编号、会话匹配和安全重试。 --- # Yolfi (https://talivia.com/zh-CN/docs/revenue-guides/yolfi) 只需连接一次 Yolfi 组织，Talivia 便会开始接收收入。 ## 连接 Yolfi [#连接-yolfi] 1. 在 Talivia 数据看板中选择网站并打开**设置**。 2. 选择**付款**和 **Yolfi**。然后[在 Yolfi 中创建接口密钥](https://app.yolfi.com/settings/api-keys)，粘贴到 Talivia 并点击**连接 Yolfi**。 ## 将付款匹配到会话 [#将付款匹配到会话] 根据客户打开 Yolfi 结账的方式选择指南。两种方式都使用返回网址中的结账会话编号，无需发送 Talivia 元数据。 付款链接 匹配在 Yolfi 控制台中创建的链接付款。 结账会话接口 匹配由后端创建的结账会话付款。 遇到问题？请[测试 Yolfi 集成](https://talivia.com/zh-CN/docs/revenue-guides/yolfi/testing-and-troubleshooting)。 --- # Yolfi 结账会话接口 (https://talivia.com/zh-CN/docs/revenue-guides/yolfi/checkout-session) 继续之前，请完成 [Yolfi 连接配置](https://talivia.com/zh-CN/docs/revenue-guides/yolfi#%E8%BF%9E%E6%8E%A5-yolfi)。 只有后端创建结账会话时才使用本指南。如果在 Yolfi 控制台中创建了可重复使用的链接，请查看[付款链接指南](https://talivia.com/zh-CN/docs/revenue-guides/yolfi/payment-link-on-your-site)。 ## 创建 Yolfi 结账会话 [#创建-yolfi-结账会话] 请将 Yolfi 接口密钥保存在后端。设置 `successUrl` 时，必须保留字面量占位符 `{CHECKOUT_SESSION_ID}`： ```javascript title="创建 Yolfi 结账会话" const checkout = await fetch('https://app.yolfi.com/api/checkout-sessions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.YOLFI_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ paylinkId: process.env.YOLFI_PAYLINK_ID, successUrl: 'https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}', }), }).then(response => response.json()); return Response.json({ url: checkout.data.url }); ``` 将客户送到 `checkout.data.url`。付款后，Talivia 会从返回页面读取 `session_id` 并自动匹配付款，无需 Talivia 元数据。 订阅的首次结账使用同一个 `successUrl`，之后的续费会自动关联到原始付款。 完整请求与响应结构请参阅 [Yolfi 结账会话](https://docs.yolfi.com/en/paylinks/checkout-sessions)。 --- # 使用 Yolfi 付款链接归因收入 (https://talivia.com/zh-CN/docs/revenue-guides/yolfi/payment-link-on-your-site) 继续之前，请完成 [Yolfi 连接配置](https://talivia.com/zh-CN/docs/revenue-guides/yolfi#%E8%BF%9E%E6%8E%A5-yolfi)。 在 Yolfi 中打开付款链接，并前往**完成付款后**。 将**付款后的操作**设为**重定向**，并使用： ```text https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID} ``` 这就是全部配置。客户返回时，Talivia 会读取 `session_id` 并自动匹配付款，无需 Talivia 元数据。 ## 共享链接与二维码 [#共享链接与二维码] 通过邮件、聊天、社交媒体或二维码共享付款链接时，同一个重定向仍然有效。如果客户从未返回运行 Talivia 追踪器的页面，付款仍会记录，但无法匹配到网站会话。 ## 订阅 [#订阅] 首次订阅结账时使用该重定向。之后的续费会自动关联到原始付款，无需再次经过浏览器重定向。 --- # 测试与排查 Yolfi (https://talivia.com/zh-CN/docs/revenue-guides/yolfi/testing-and-troubleshooting) ## 测试付款 [#测试付款] 1. [连接 Yolfi](https://talivia.com/zh-CN/docs/revenue-guides/yolfi#%E8%BF%9E%E6%8E%A5-yolfi)。 2. 从安装了 Talivia 追踪器的页面打开结账。 3. 完成付款并返回网站。 4. 确认付款以预期流量来源出现在 Talivia 中。 ## 连接失败 [#连接失败] * 在 [Yolfi 接口设置](https://app.yolfi.com/settings/api-keys)中创建新密钥。 * 确认密钥属于要连接的组织。 * 将新密钥粘贴到 Talivia 并重新连接。 ## 没有出现付款 [#没有出现付款] 确认**网站设置 → 付款**中的 Yolfi 仍处于已连接状态，然后再完成一笔测试付款。无需在付款中添加网站编号或 Talivia 元数据。 ## 付款未归因 [#付款未归因] 确认成功页面安装了 Talivia 追踪器，并且重定向网址包含： ```text https://merchant.example/thanks?session_id={CHECKOUT_SESSION_ID} ``` 对于续费，首次订阅付款必须先匹配成功，后续付款才能复用其归因。 --- # 会话 (https://talivia.com/zh-CN/docs/sessions) 会话展示某位访客在一次访问期间如何浏览网站。Talivia 将页面浏览、自定义事件、来源信息、追踪参数和付款活动合并到同一条活动时间线中。 ## 会话列表 [#会话列表] 从网站中打开**会话**，查看最近的会话。每一行都会显示来源、访问次数、事件、活动，以及会话已关联收入时的消费金额。 打开完整的会话报表。点击“会话”面板右上角的展开图标。在完整报表中选择任意会话，即可查看详细活动时间线、来源、设备、位置、事件和归因消费。 ## 会话详情 [#会话详情] 会话详情视图包含： * 到达来源、引荐来源、页面和追踪参数。 * 按时间顺序排列的页面浏览和自定义事件。 * 浏览器、操作系统、设备、国家或地区、地区和城市。 * 已完成归因时的付款活动和消费金额。 * 启用录制后的会话回放。 ## 排序 [#排序] 活动可以按从早到晚或从晚到早查看。需要按照访客实际经历理解完整路径时，请选择从早到晚。 --- # 子域名追踪 (https://talivia.com/zh-CN/docs/subdomain-tracking) 在所有子域名上使用同一个 Talivia 网站编号，并将根域名设为相同的 `data-domain`： ```html ``` 此配置适用于以下流程： ```text example.com -> app.example.com -> checkout.example.com ``` 如果网站只运行在一个主机名上，此配置不是必需的：追踪器可以使用仅限当前主机的 Cookie。Talivia 云服务生成的代码片段会包含 `data-domain`，避免日后迁移到子域名时悄无声息地拆分访客身份。 Talivia 将匿名访客 Cookie 保存 365 天，并在每次活动后将共享会话 Cookie 的有效期延长 30 分钟。因此，不同标签页和子域名会保留在同一段访问路径中，而不会生成多个访客。 请使用可注册的根域名（`example.com`）。如果访客还会访问 `example.com`，请勿设置 `data-domain="app.example.com"`。 --- # 标签 (https://talivia.com/zh-CN/docs/tags) 标签用于标记来自特定脚本安装位置或环境的事件。 ```html ``` 该脚本发送的每个事件都会包含此标签。 ## 常见用途 [#常见用途] * 营销网站和应用共用同一网站编号时区分两者。 * 标记嵌入式体验。 * 比较不同发布版本。 * 无需创建第二个网站即可排查预发布环境流量。 ## 筛选 [#筛选] 标签会作为事件维度显示，可用于筛选、数据细分和事件级调查。 --- # 团队 (https://talivia.com/zh-CN/docs/team) 团队权限按网站分别管理。共享给您的网站会直接显示在数据看板中，因此无需另行切换团队。 ## 邀请用户 [#邀请用户] 打开**设置 → 团队**，输入已注册 Talivia 用户的电子邮箱，选择角色并点击**邀请**。该用户应使用同一个电子邮箱登录，随后即可看到网站。 ## 角色 [#角色] * **查看者**对数据看板、报表和会话拥有只读权限。 * **成员**还可以修改网站设置和集成。 * **所有者**负责管理邀请和访问权限，并可删除网站。 ## 管理权限 [#管理权限] “团队”页面会显示网站所有者及每位受邀用户当前的角色。某位用户不再需要权限时，所有者可以修改其角色或将其移除。 外包工作结束、代理服务交接或其他临时协作完成后，请重新检查成员列表。 --- # 追踪事件 (https://talivia.com/zh-CN/docs/track-events) 自定义事件适合追踪比页面浏览更重要的操作，例如注册、点击结账、申请演示、打开外部链接和完成激活步骤。 ## HTML 属性 [#html-属性] 为元素添加 `data-talivia-event`： ```html ``` 使用 `data-talivia-event-*` 属性添加事件数据： ```html ``` 点击时，Talivia 会自动读取这些属性。 ## 元素进入可见区域时追踪 [#元素进入可见区域时追踪] 为重要元素添加 `data-talivia-visible`，例如价格区域、行动按钮、横幅、提醒或弹窗。 ```html

Simple pricing

``` 当元素 50% 的区域进入可见范围时，Talivia 会在每次页面浏览中发送一次 `pricing-seen` 事件。 如果默认值不适合该元素，可使用以下可选属性： ```html ``` * `data-talivia-visible-threshold` 可设为 `0.1` 到 `1`，默认值为 `0.5`。 * `data-talivia-visible-delay` 要求元素持续可见指定时长后再发送事件，默认值为 `0` 毫秒。 可见性事件的数据中包含 `visibility_percentage`、`threshold` 和 `delay`。它们与其他 Talivia 事件一样，可用于会话、目标和转化漏斗。 ## 链接 [#链接] 对于普通链接，Talivia 会尽可能等待事件请求发出后再跳转。 ```html Pricing ``` 外部链接、配合修饰键的点击以及 `_blank` 链接不会被延迟。 ## JavaScript [#javascript] ```js window.talivia.track('invite-sent', { role: 'viewer', }); ``` 事件取决于应用状态、表单结果或服务器响应时，请使用 JavaScript。 ## 事件数据建议 [#事件数据建议] * 使用 `signup-click` 之类稳定的名称，不要使用会变化的按钮文案。 * 以后需要进行数值比较时，请将数值保留为数字类型。 * 除非付款归因确实需要且符合您的隐私政策，否则请勿发送个人信息。 --- # 追踪器配置 (https://talivia.com/zh-CN/docs/tracker-configuration) 追踪器会读取脚本标签上的 `data-*` 属性。对于常规 Talivia 云服务安装，请从**设置 → 数据追踪**复制完整代码片段，并保持生成的属性不变。 ```html ``` 只追踪一个主机名时，仅 `data-website-id` 为必填项。Talivia 云服务通常也会生成 `data-domain`；保留它是安全的，并可让多个子域名延续同一匿名身份。 ## 域名属性 [#域名属性] 下面几个名称相似的属性分别解决不同问题： | 属性 | 用途 | | --------------------------- | ----------------------------------------------------------------------- | | `data-domain` | 设置 Cookie 范围。当同一访客会在 `example.com` 与其子域名之间移动时，请使用 `example.com` 这样的根域名。 | | `data-domains` | 限制允许此脚本采集数据的主机名，不会用于共享身份。 | | `data-cross-domain-domains` | 使用签名连接令牌，在 `example.com` 与 `example.net` 等不同根域名之间延续访问路径。 | 网站只运行在一个主机名上时，无需手动配置域名。子域名请参阅[子域名追踪](https://talivia.com/zh-CN/docs/subdomain-tracking)，不同根域名请参阅[跨域追踪](https://talivia.com/zh-CN/docs/cross-domain-tracking)。 ## 可用属性 [#可用属性] | 属性 | 说明 | | --------------------------- | ------------------------------------------------ | | `data-website-id` | 必填的网站编号。 | | `data-host-url` | 自行托管或使用自定义反向代理时覆盖数据采集接口来源。常规 Talivia 云服务安装请勿设置。 | | `data-domain` | 网站及其子域名共享的可选 Cookie 域名。Talivia 云服务会根据已配置的网站域名生成。 | | `data-auto-track` | 设为 `false` 可关闭首次自动页面浏览。 | | `data-domains` | 可选的逗号分隔主机名允许列表。共享身份时无需逐一列出子域名。 | | `data-cross-domain-domains` | 允许接收 Talivia 签名连接令牌的逗号分隔根域名。 | | `data-do-not-track` | 设为 `true` 可遵循浏览器的“请勿追踪”设置。 | | `data-exclude-search` | 设为 `true` 可在发送网址前移除查询字符串。 | | `data-exclude-hash` | 设为 `true` 可在发送网址前移除井号片段。 | | `data-tag` | 为此脚本发送的每个事件附加标签。 | | `data-before-send` | 可修改或取消负载的全局函数名。 | | `data-fetch-credentials` | Fetch 凭据模式，默认为 `omit`。 | | `data-performance` | 设为 `true` 可采集网页核心性能指标。 | ## beforeSend [#beforesend] ```html ``` 返回 `null` 或 `undefined` 即可取消事件。 ## 域名允许列表 [#域名允许列表] 这是可选限制，并非子域名追踪的必要条件。 ```html ``` 一个根域名条目会覆盖该域名及其子域名。当同一布局可能显示在预发布、预览和生产域名上时，此限制很有用。 ## 数据采集主机 [#数据采集主机] 脚本会自动把数据发送到 Talivia 云服务。`data-host-url` 只适用于自行托管和自定义反向代理，即浏览器必须将采集请求发送到其他来源的情况。它不是被追踪网站的附加网址，常规云服务代码片段中应省略。 ## 身份存储 [#身份存储] Talivia 将匿名访客标识符和滚动会话标识符保存在第一方 Cookie 中。 ## 访客与会话有效期 [#访客与会话有效期] * 匿名访客 Cookie 的有效期为 365 天。 * 会话 Cookie 的有效期为 30 分钟，追踪器每次发送活动时都会刷新。 * 关闭标签页不会拆分仍在活动的会话。所有标签页和已配置子域名都会重复使用同一个滚动会话。 多个子域名需要共享身份时，请将 `example.com` 这样的可注册根域名用于 `data-domain`，不要使用 `app.example.com`。手动修改前，请从**设置 → 数据追踪**复制生成的代码片段并阅读[子域名追踪](https://talivia.com/zh-CN/docs/subdomain-tracking)。 ## 敏感查询参数 [#敏感查询参数] Talivia 会从存储的网址查询中移除 OAuth 凭据、签名跨域令牌和结账会话编号。付款返回检测会在清理之前运行，因此 Stripe 及其他结账归因仍可正常工作，同时不会在分析数据中显示机密信息。 --- # 追踪器函数 (https://talivia.com/zh-CN/docs/tracker-functions) 脚本加载后，追踪器会提供一组精简的浏览器接口。 ## 追踪页面浏览 [#追踪页面浏览] ```js window.talivia.track(); ``` 关闭自动追踪，或需要在路由切换后手动发送页面浏览时使用此调用。 ## 追踪自定义事件 [#追踪自定义事件] ```js window.talivia.track('signup-button'); ``` 事件名称最多 50 个字符。 ## 追踪带数据的事件 [#追踪带数据的事件] ```js window.talivia.track('signup-button', { plan: 'pro', location: 'pricing', }); ``` 事件数据可以包含字符串、数字、数组和嵌套对象。请保持负载精简：Talivia 会截断过长字符串并限制对象结构，以确保报表响应迅速。 ## 覆盖页面属性 [#覆盖页面属性] ```js window.talivia.track({ website: 'YOUR_WEBSITE_ID', url: '/pricing', title: 'Pricing', }); ``` ## 使用函数 [#使用函数] ```js window.talivia.track(props => ({ ...props, url: '/checkout', title: 'Checkout', })); ``` 该函数会接收当前追踪负载，并返回需要发送的负载。 ## 识别访客 [#识别访客] ```js window.talivia.identify('user_123', { email: 'founder@example.com', stripeCustomerId: 'cus_123', }); ``` 请在登录或注册后调用 `identify`。Talivia 会保存会话数据，并可将付款服务商的客户关联到访客。 ## 读取结账上下文 [#读取结账上下文] ```js const sessionId = window.talivia.getSessionId(); await fetch('/api/create-checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId }), }); ``` `getSessionId()` 返回第一方 Cookie `talivia_session_id` 中保存的不透明值。只需把这个值发送给后端，并以 `talivia_session_id` 服务商元数据附加到付款。它是归因标识符，不是身份验证凭据。 --- # 追踪概览 (https://talivia.com/zh-CN/docs/tracking) Talivia 浏览器追踪器会自动记录页面浏览，并提供一组精简的 JavaScript 接口，用于自定义事件、身份识别和结账归因。 ## 脚本 [#脚本] ```html ``` 脚本会读取浏览器上下文、监测客户端路由变化并发送页面浏览。默认情况下，Talivia 将匿名访客 Cookie 保存一年，并维护一个活动后延长 30 分钟的会话 Cookie。 只有一个主机名时，不设置 `data-domain` 也能正常工作。Talivia 云服务生成的代码片段会包含它，因此 `example.com`、`app.example.com` 和其他子域名可以在需要时共享同一访客与会话。请保留**设置 → 数据追踪**中的完整代码片段，不要根据本示例自行重新拼装。 可选脚本设置请参阅[追踪器配置](https://talivia.com/zh-CN/docs/tracker-configuration)，完整的共享 Cookie 配置请参阅[子域名追踪](https://talivia.com/zh-CN/docs/subdomain-tracking)。 ## 运行时接口 [#运行时接口] 脚本加载后会创建 `window.talivia`： ```js window.talivia.track(); window.talivia.track('signup-click'); window.talivia.identify('user_123', { email: 'founder@example.com' }); window.talivia.getSessionId(); ``` ## 数据采集接口 [#数据采集接口] 追踪器会向 Talivia 的采集接口发送数据，并接收签名缓存令牌和跨域令牌。这些令牌有效期很短，只包含匿名追踪键，不包含账户或付款凭据。 ## 收入上下文 [#收入上下文] 结账流程请按照已连接服务商的收入指南操作。Stripe 和 Yolfi 会在浏览器返回时使用唯一的结账会话编号。无法提供返回信号的服务商，可以在其支持的结账元数据中使用 `window.talivia.getSessionId()`。 --- # 获取更新 (https://talivia.com/zh-CN/docs/updates) Talivia 云服务会自动更新。托管应用发布新功能时，您无需手动升级追踪脚本。 ## 追踪器更新 [#追踪器更新] 脚本通过 Talivia 使用 `defer` 加载，因此浏览器每次请求 `script.js` 时，访客都会获得最新的兼容版本。 如果网站使用严格的内容安全策略，请确保允许 Talivia 脚本来源和数据采集接口。 ## 产品更新 [#产品更新] 新的数据看板功能无需修改网站即可出现。例如，收入归因、搜索词报表和会话回放都会使用已经由追踪器及已连接集成持续传入的数据。 ## 何时需要修改代码 [#何时需要修改代码] 只有在主动启用新的追踪行为时才需要修改网站代码，例如： * 添加自定义事件属性。 * 调用 `window.talivia.identify`。 * 将 `window.talivia.getSessionId()` 传入结账流程。 * 使用 `data-performance="true"` 启用性能采集。 --- # UTM 参数 (https://talivia.com/zh-CN/docs/utm) Talivia 会记录页面网址中的标准 UTM 参数： * `utm_source` * `utm_medium` * `utm_campaign` * `utm_content` * `utm_term` 它还会记录 `gclid`、`fbclid`、`msclkid`、`ttclid`、`li_fat_id` 和 `twclid` 等常见广告点击标识符。 ## 推广活动流程 [#推广活动流程] 1. 在推广链接中添加 UTM 参数。 2. 将流量引导至已安装追踪器的页面。 3. 查看 UTM 报表和细分数据。 4. 连接收入数据，了解哪些推广活动带来了付费会话。 ## 清理查询参数 [#清理查询参数] 在**设置 → 归因 → 忽略的查询参数**中配置不需要保存的干扰参数。