mcpField
I
integration-astro-view-transitions

integration-astro-view-transitions

github.com/posthog数据与数据库7694 次安装今天更新
代码仓库

关于 integration-astro-view-transitions

用于将 PostHog 分析接入采用 View Transitions 的 Astro 应用的技能，按阶段引导配置，并提供页面浏览、用户识别和错误跟踪的框架实践。

主要功能

  1. 01分阶段配置流程
  2. 02Astro View Transitions 实践
  3. 03可复用的 PostHog 初始化
  4. 04用户识别指导
  5. 05错误跟踪指导

适用场景

  1. 01为 Astro 网站添加 PostHog 分析
  2. 02跟踪软导航期间的页面浏览
  3. 03关联前后端用户身份
  4. 04为关键流程添加错误跟踪

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill integration-astro-view-transitions

安装后在 Claude Code 中输入/integration-astro-view-transitions确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
astro.md
basic-integration-1.0-begin.md
basic-integration-1.1-edit.md
basic-integration-1.2-revise.md
basic-integration-1.3-conclude.md
EXAMPLE.md
identify-users.md

详细介绍

Astro（视图转换）的 PostHog 集成

此技能可帮助你将 PostHog 分析添加到 Astro（视图转换）应用中。

工作流

按以下步骤依次完成集成：

  1. basic-integration-1.0-begin.md - PostHog 设置 - 开始 ← 从这里开始
  2. basic-integration-1.1-edit.md - PostHog 设置 - 编辑
  3. basic-integration-1.2-revise.md - PostHog 设置 - 修改
  4. basic-integration-1.3-conclude.md - PostHog 设置 - 完成

参考文件

  • references/EXAMPLE.md - Astro（视图转换）示例项目代码
  • references/astro.md - Astro - 文档
  • references/identify-users.md - 识别用户 - 文档
  • references/basic-integration-1.0-begin.md - PostHog 设置 - 开始
  • references/basic-integration-1.1-edit.md - PostHog 设置 - 编辑
  • references/basic-integration-1.2-revise.md - PostHog 设置 - 修改
  • references/basic-integration-1.3-conclude.md - PostHog 设置 - 完成

示例项目展示了目标实现模式。API 详情请参阅文档。

核心原则

  • 环境变量：始终使用环境变量保存 PostHog 密钥。切勿将其硬编码。
  • 尽量少改动：在现有集成旁添加 PostHog 代码。不要替换或重构现有代码。
  • 遵循示例：实现应尽可能贴近示例项目中的模式。

框架指南

  • 始终在 PostHog 脚本标签上使用 is:inline 指令，避免 Astro 处理这些标签并导致 TypeScript 错误
  • 在 Astro 中，客户端环境变量使用 PUBLIC_ 前缀（例如，PUBLIC_POSTHOG_PROJECT_TOKEN）
  • 在 src/components/ 中创建 posthog.astro 组件，以便在多个页面间复用初始化逻辑
  • 在一个 Layout 中导入 PostHog 组件，并用该布局包裹所有页面
  • 使用 window.__posthog_initialized 防护条件包裹 PostHog 初始化，避免软导航期间发生堆栈溢出
  • 将 capture_pageview 选项设为 'history_change'，以便在软导航期间自动跟踪页面浏览
  • 使用 astro page-load 事件，而不只是 DOMContentLoaded，以便在软导航后重新运行脚本

识别用户

在登录和注册事件期间识别用户。有关此框架的正确识别模式，请参阅示例代码和文档。如果同时存在前端和后端代码，请使用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 标头传递客户端会话 ID 和 distinct ID，以保持关联。

错误跟踪

在相关文件中添加 PostHog 错误跟踪，尤其是在关键用户流程和 API 边界处。

评论

支持 Markdown