为新应用添加 PostHog 和 Clerk 涉及设置两个解决不同问题的独立系统。Clerk 处理用户登录您的应用,而 PostHog 跟踪用户进入应用后的操作。您可以通过它们的管理平台和软件开发工具包 (SDK) 手动配置它们,或者使用 Stripe Projects 来配置它们,后者会将这两个提供商的凭据直接提取到您项目的 .env 文件中,而无需您在不同的管理平台之间跳转。
超过 50 万个团队和近 25 万名工程师在使用 PostHog。许多团队最终会将 PostHog 与身份验证提供商(例如 Clerk)配对使用。Stripe Projects 通过在单一工作流中配置这两项服务,简化了该设置。
下面,我们将讨论每个提供商的作用,为什么将经过身份验证的身份与分析事件联系起来有助于您了解的不仅仅是流量,以及如何使用 Stripe Projects 快速添加 PostHog 和 Clerk。
要点
将 Clerk 经过身份验证的用户标识符 (ID) 连接到 PostHog 的
identify()方法,可将匿名会话数据转化为已识别的用户资料,而不会丢失登录前的事件历史记录。Stripe Projects 可以通过命令行界面 (CLI) 命令配置 PostHog 和 Clerk,这些命令可处理账户授权并将凭据直接写入您项目的
.env文件中。PostHog 和 Clerk 的最佳实践包括干净地分离环境,并尽量减少事件属性中的个人数据。
什么是 PostHog 和 Clerk?
PostHog 是一个产品分析平台。它跟踪应用内的事件、页面浏览量和用户行为,然后将这些数据转化为漏斗、会话记录、功能标志和同类群组分析。Clerk 是一家身份验证和用户管理提供商。它处理注册、登录、会话令牌、多因素身份验证和用户资料数据。
为什么要将 PostHog 分析与 Clerk 身份验证结合使用?
将 PostHog 与 Clerk 结合使用,您可以获得有关漏斗顶部流量的分析,例如流失预测、入驻分析或功能采用情况(按账户层级细分)。PostHog 通过一个不同的 ID 来跟踪用户,该 ID 最初是与浏览器或设备绑定的匿名随机生成的标识符。当用户通过 Clerk 登录时,您可以调用 PostHog 的 identify() 方法,并将 Clerk 的用户 ID 作为新的不同 ID 传递。然后,PostHog 会将匿名会话历史记录与已识别的资料合并,将登录前跟踪的事件(例如页面浏览、按钮点击和功能交互)链接到该用户。
请密切注意以下细节:
事件命名一致性: 尽早决定事件是采用蛇形命名法(例如,不带空格)还是首字母大写命名法,以及它们是描述操作(例如
signed\_up)还是对象(例如signup\_completed)。混合使用这些约定会使您的 PostHog 管理平台变得难以阅读。匿名用户与已识别用户: 如果您在每次页面加载时调用
identify(),您将在 PostHog 的活动日志中累积重复的合并事件。在 Clerk 确认会话后,只需调用一次即可。您也可以在检查用户是否已在当前会话中被识别之后再进行调用。隐私和同意: 在对跟踪有同意要求的管辖区(例如欧盟的 欧盟《通用数据保护条例》(GDPR) 规定),在识别用户或将个人数据附加到事件属性之前,请先获取同意。在每个分析事件中提供电子邮件或姓名通常是不必要的,并且会扩大您的合规面。
何时连接两者: 如果您的应用主要是注册前的营销页面,那么匿名跟踪就足够了。一旦您有值得衡量的经过身份验证的流程(例如从试用到付费的转化),请连接 Clerk 和 PostHog 事件。
如何手动配置 PostHog 和 Clerk?
您将在四个系统中手动配置这两个提供商:两个管理平台和两个 SDK。
运作机制如下:
1. 创建 PostHog 项目
在 PostHog 注册并创建一个项目。这将为您提供一个项目应用程序编程接口 (API) 密钥和主机 URL。SDK 将需要这两个值。
2. 创建 Clerk 应用程序
在 Clerk 管理平台中,创建一个应用程序并选择您的登录方法,例如电子邮件、Google OAuth 或通行密钥。
3. 安装 SDK
对于 Next.js 应用,请运行 npm install posthog-js 和 npm install @clerk/nextjs。PostHog 通过 posthog.init() 在客户端初始化,而 Clerk 将您的应用包装在 \<ClerkProvider\> 中,并需要中间件来处理路由保护。
4. 设置环境变量
将四到六个值添加到您的 .env.local 文件中。
5. 测试设置
确认 Clerk 的登录流程生成了一个会话,然后检查 PostHog 的实时事件视图以确认事件正在传入。验证 identify() 每个会话是否仅在身份验证完成后精确触发一次。
如何使用 Stripe Projects 浏览分析提供商?
Stripe Projects 是一项 Stripe CLI 功能,用于直接从命令行配置第三方基础结构服务,包括数据库、分析和 AI 提供商。您无需为每项服务打开单独的管理平台,而是可以从与您的项目绑定的一个界面浏览和配置它们。
您可以在项目目录中运行 Stripe Projects 以列出可用的提供商(按类别和服务层级组织),从而浏览分析功能的提供商选项。您可以使用 stripe projects catalog \<provider\> 或 stripe projects catalog \<category\> 来缩小范围,或使用 stripe projects search \<keyword\> 直接搜索。如果您专门寻找分析服务,您将看到 PostHog 以及其他受支持的提供商,从而无需离开终端或切换到浏览器。
如何使用 Stripe Projects 添加 PostHog 和 Clerk?
选择了 PostHog 和 Clerk 后,只需两个命令即可从已使用 Stripe CLI 初始化的项目中配置这两项服务。要添加 PostHog,请运行 stripe projects add posthog/analytics 以启动配置流程。Stripe Projects 会处理账户授权步骤(通常需要您直接登录 PostHog 并手动复制密钥)。然后,它会将生成的 API 密钥和主机 URL 写入您项目的 .env 文件中。运行 stripe projects add clerk/auth 可对 Clerk 执行相同的操作:它管理授权流程并检索可发布密钥和私密密钥。这些内容将与 PostHog 刚才添加的内容一起写入 .env 中。
使用 Stripe Projects 设置与手动设置之间的实际区别在于凭据的来源。您无需从两个管理平台中复制密钥并将其粘贴到 .env.local 中,Stripe Projects 会直接检索并写入它们,尽管您(或您的编码代理)仍需自己编写 SDK 初始化代码并连接您的应用逻辑。
您还需要保持密钥同步。如果您是首次在新机器上设置项目,stripe projects pull \<projectID\> 会将现有项目克隆到一个空目录中,并写入您的 .env 文件,这会连接到项目现有的服务而不是配置新服务。如果您已经在项目目录中,并且需要在团队成员添加或轮换提供商后刷新本地 .env,请改为运行 stripe projects pull env \--pull。
PostHog 和 Clerk 的最佳实践是什么?
在发布此集成之前,有几件事值得妥善处理。
以下是需要注意的事项:
干净地分离环境: 对于开发和生产环境,请使用不同的 PostHog 项目和 Clerk 应用程序。将测试注册数据与真实用户数据混合会使您的分析变得不可靠,并使您的 Clerk 用户列表中充斥着一次性账户。
绝对不要在客户端暴露 Clerk 私密密钥: 它只属于服务器端环境变量。可发布密钥对于浏览器是安全的;而私密密钥则不安全。
尽量减少事件属性中的个人数据: 发送用户 ID 而不是电子邮件地址,因为如果以后需要,仅凭 ID 就可以将数据连接回 Clerk 的用户表。
在识别用户之前尊重同意: 如果您的管辖区要求跟踪需获得同意,请在获得该同意之后再调用
identify()。明确测试合并行为: 以匿名用户身份注册,生成几个事件,然后登录并确认 PostHog 将该历史记录合并到已识别的资料下,而不是启动一个未连接的新资料。
记录您的事件模式: 使用共享的事件名称和属性参考,可防止团队的不同部门在三个不同的名称下跟踪同一操作。
Stripe Projects 如何提供帮助
Stripe Projects 允许开发者及其 AI 代理从命令行界面 (CLI) 添加服务、生成凭据和管理计费。
Stripe Projects 可帮助您:
从命令行配置第三方服务: 使用单一工作流来添加服务、管理凭据和升级方案,而无需为每个提供商使用不同的工具和工作流。管理托管、数据库、身份验证、AI 等,无需管理平台、配置文件或基础结构代码。
自动同步凭据: 保持环境变量在本地设置、机器、团队成员和代理之间可移植——无需复制粘贴应用程序编程接口 (API) 密钥。
从 CLI 或您的编码代理管理计费: 一次性设置计费详情,并将其安全地分享给第三方服务。从 CLI 升级和降级定价层级、监控用量和管理订阅。
了解有关 Stripe Projects 如何帮助简化应用配置的更多信息,或将此命令复制并粘贴到您的终端中以立即开始使用:
本文中的内容仅供一般信息和教育目的,不应被解释为法律或税务建议。Stripe 不保证或担保文章中信息的准确性、完整性、充分性或时效性。您应该寻求在您的司法管辖区获得执业许可的合格律师或会计师的建议,以就您的特定情况提供建议。