在 Scalar API Client 中接入 PostHog 分析PostHogClientPlugin 插件配置与隐私保护实战【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本篇技术指南围绕 Scalar 开源仓库中 PostHog Plugin for Scalar API Client 展开讲解如何在独立部署的 Scalar API Client以及内嵌 API Client 的 API Reference中接入 PostHog 产品分析从安装依赖、初始化配置、事件上报到基于白名单的隐私数据过滤与telemetry开关的运行时联动。读完本文你将能够为自托管或嵌入式的 Scalar 组件正确接入 PostHog并理解其默认不追踪、显式启用、白名单上报的隐私设计思路。插件定位加载即启用不加载零追踪Scalar 是一个开源 API 平台其核心组件 packages/api-client 提供了现代化的 REST API 客户端能力。PostHog 插件是附着在该客户端之上的分析插件通过posthog-js将用户行为事件上报到自建或托管的 PostHog 实例。插件的行为模式非常简单且克制加载插件 显式选择启用分析opt in只有当你把PostHogClientPlugin加入插件列表时客户端才会初始化 PostHog 并开始捕获事件不加载插件 不产生任何追踪源码注释中明确写着 If the plugin is not loaded, no tracking occurs见 index.ts面向 API Reference 用户有专属方案如果使用内嵌 API Client 的 API Reference应改用 API Reference PostHog 插件它会同时处理 API Reference 与内嵌 API Client 两个产品的分析无需分别接入。安装依赖插件基于posthog-js实现首先需要安装它npm install posthog-js快速开始最小可运行的接入示例在 API Client 的插件数组中加入PostHogClientPlugin传入项目 API Key 与 API Host 即可import { PostHogClientPlugin } from scalar/api-client/plugins/posthog const plugins [ PostHogClientPlugin({ apiKey: phc_your_project_api_key, apiHost: https://us.i.posthog.com, }), ]PostHogClientPlugin是一个工厂函数返回类型为ClientPlugin定义见 packages/oas-utils/src/helpers/client-plugins.ts它同时提供了on事件监听器与lifecycle生命周期钩子可无缝挂入 API Client 的插件系统on订阅事件总线上的全部事件通过bus.onAny转发用于按需捕获lifecycle.onInit/onConfigChange/onDestroy分别在客户端初始化、配置变更、销毁时执行负责 PostHog 实例的创建、启用/停用捕获与清理。配置项详解OptionTypeRequiredDescriptionapiKeystringYes你的 PostHog 项目 API Keyphc_前缀apiHoststringYesPostHog API 主机地址上报数据的端点uiHoststringNoPostHog UI 主机地址用于会话录制、问卷调查等功能的资源加载defaultsConfigDefaultsNoPostHog 的 defaults 版本标识从源码index.ts可以看到PostHogConfig类型与 README 表格一一对应uiHost与defaults均为可选配置只在提供时才会被透传给posthog-js的初始化参数。具体映射逻辑如下const instance ph.init( config.apiKey, { api_host: config.apiHost, ...(config.uiHost ? { ui_host: config.uiHost } : {}), ...(config.defaults ? { defaults: config.defaults } : {}), opt_out_capturing_by_default: true, }, scalar-api-client, )值得注意的两个细节实例命名空间ph.init的第三个参数是实例名称scalar-api-client这使多个产品如 API Reference 使用scalar-api-reference可以在同一页面共享 PostHog 而互不干扰默认关闭捕获初始化时强制opt_out_capturing_by_default: true随后插件根据 API Client 的telemetry配置决定是否调用opt_in_capturing()——这正是加载即启用与telemetry 开关两层控制的落点。事件上报与隐私保护白名单 字段提取插件并非把所有事件一股脑上报而是通过 sanitize-event-payload.ts 中的TRACKED_EVENTS白名单做两层过滤第一层事件白名单。每个事件要么映射到一个提取器extractor要么显式标记为undefinedopt-out。不在映射表中的事件会被静默丢弃。源码注释明确指出被标记为undefined的事件是刻意不追踪的例如auth:update:security-scheme-secrets安全方案密钥operation:update:requestBody:value请求体内容operation:upsert:parameter参数内容select:nav-item、analytics:on:loaded等这种设计有一个工程上的巧妙之处新事件加入事件总线后只要开发者没有有意识地把它放进白名单或显式标记 opt-outTypeScript 会直接报类型错误从而强制对每个新事件的追踪决策进行显式评审。第二层字段提取。对被追踪的事件只提取安全、非 PII的属性其余字段一律剥离。提取器基于scalar/helpers/object/get-value-at-path实现例如auth:update:selected-security-schemes提取meta.type认证方式类型如apiKey/bearercookie:upsert:cookie、environment:upsert:environment提取collectionType区分document还是workspaceui:download:document提取formatjson/yamlworkspace:update:active-proxy提取布尔值enabled当提取器返回的属性集合为空时插件只调用posthog?.capture(event)而不携带 properties避免上报一堆无意义的{}噪音。测试用例 sanitize-event-payload.test.ts 专门验证了即使事件被追踪也会剥离未知字段这一行为payload 中混入secret、body等敏感字段时最终只会上报collectionType。登录/登出与生命周期身份识别与数据清理插件对用户身份事件有专门处理见 index.tslog:user-login不会把登录事件本身作为普通事件捕获而是在 payload 携带uid时调用posthog.identify(uid, { email, teamUid })完成用户关联log:user-logout调用posthog.reset()清空当前用户上下文避免后续匿名事件与上一用户错误关联onDestroy插件销毁时同样调用reset()并置空实例引用确保组件卸载后不再上报。与 telemetry 配置联动运行时动态开关插件尊重 API Client 的telemetry配置选项并且在运行时动态响应配置变更onConfigChange(context) { if (!posthog) return if (context.config.telemetry false) { posthog.opt_out_capturing() } else { posthog.opt_in_capturing() } }telemetry未设置或非false初始化时即opt_in_capturing()开始上报telemetry: false初始化时保持 opt-out 状态不产生任何上报即使运行中改为falseonConfigChange也会立即停用捕获。这一行为在 posthog-plugin.test.ts 中有完整覆盖测试分别验证了初始化时不 opt-in、配置变更为false时opt_out_capturing被调用、配置恢复时opt_in_capturing被调用三种场景。在 API Reference 中使用一键覆盖两个产品如果你使用的是 API Reference它内嵌了 API Client请引入 packages/api-reference/src/plugins/posthog/index.ts 中的PostHogPlugin而不是直接使用PostHogClientPlugin。它的实现方式是组合内部创建一份PostHogClientPlugin(config)并在onInit时透传调用其onInit/onConfigChange/onDestroy同时以scalar-api-reference名称初始化一个 PostHog 实例并通过posthog.register({ product: api-reference })标记产品维度通过apiClientPlugins: [clientPlugin]把客户端插件注册给内嵌的 API Client。这样API Reference 与内嵌的 API Client 各自以product属性区分上报一份配置同时覆盖两个产品。README 中同样提示了这一点并指向该插件作为 API Reference 场景的正确入口。真实项目中的接入示例在 Scalar 官方客户端应用 projects/scalar-app/src/App.vue 中可以看到插件与请求脚本插件并列使用的真实形态const plugins [ requestScriptsPlugin(), PostHogClientPlugin({ apiKey: phc_3elIjSOvGOo5aEwg6krzIY9IcQiRubsBtglOXsQ4Uu4, apiHost: https://magic.scalar.com, uiHost: https://us.posthog.com, }), ]这个示例展示了两个实践要点uiHost与apiHost可以指向不同地址——apiHost负责数据上报uiHost负责会话录制/问卷等 UI 资源插件系统支持多插件共存PostHog 插件只是ClientPlugin接口的一个普通实现。测试与验证插件的每个关键行为都有 Vitest 测试背书可作为接入或二次开发时的行为契约posthog-plugin.test.ts验证生命周期钩子存在、初始化时注册product: api-client、telemetry 开关联动、白名单事件捕获、登录 identify/登出 reset、销毁 reset以及非白名单事件如auth:update:security-scheme-secrets、operation:update:requestBody:value绝不捕获sanitize-event-payload.test.ts验证各提取器在字段缺失、类型错误如meta.type为数字、collectionType为null时返回空对象而非抛错并验证TRACKED_EVENTS中每个被追踪事件都有提取器、每个 opt-out 事件都显式为 undefined、二者合计覆盖全部事件键的完整性约束。测试中还通过vi.mock(posthog-js)与vi.stubGlobal(window, globalThis)模拟浏览器环境侧面印证了该插件仅面向浏览器运行环境、且初始化时对typeof window undefined做了防御性判断SSR 场景下直接跳过初始化。小结接入路径与隐私心智模型为 Scalar API Client 接入 PostHog 的完整决策路径如下先判断使用场景独立 API Client 用PostHogClientPlugin内嵌于 API Reference 则用PostHogPlugin安装posthog-js用apiKeyapiHost初始化按需补充uiHost、defaults遵循默认不追踪不加载插件即零上报加载后可通过telemetry: false全局关闭且运行时动态生效信任白名单机制事件与字段都被显式过滤密钥、请求体、参数等敏感数据不会进入 PostHog任何新事件都必须经过显式的追踪决策。这套显式 opt-in 白名单 字段提取 生命周期清理的组合让分析能力的接入与数据隐私的保护在同一个插件内达成平衡无论是自托管 PostHog 还是接入官方云服务都可以直接复用本文的配置模式。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Scalar API Client 中接入 PostHog 分析：PostHogClientPlugin 插件配置与隐私保护实战
在 Scalar API Client 中接入 PostHog 分析PostHogClientPlugin 插件配置与隐私保护实战【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本篇技术指南围绕 Scalar 开源仓库中 PostHog Plugin for Scalar API Client 展开讲解如何在独立部署的 Scalar API Client以及内嵌 API Client 的 API Reference中接入 PostHog 产品分析从安装依赖、初始化配置、事件上报到基于白名单的隐私数据过滤与telemetry开关的运行时联动。读完本文你将能够为自托管或嵌入式的 Scalar 组件正确接入 PostHog并理解其默认不追踪、显式启用、白名单上报的隐私设计思路。插件定位加载即启用不加载零追踪Scalar 是一个开源 API 平台其核心组件 packages/api-client 提供了现代化的 REST API 客户端能力。PostHog 插件是附着在该客户端之上的分析插件通过posthog-js将用户行为事件上报到自建或托管的 PostHog 实例。插件的行为模式非常简单且克制加载插件 显式选择启用分析opt in只有当你把PostHogClientPlugin加入插件列表时客户端才会初始化 PostHog 并开始捕获事件不加载插件 不产生任何追踪源码注释中明确写着 If the plugin is not loaded, no tracking occurs见 index.ts面向 API Reference 用户有专属方案如果使用内嵌 API Client 的 API Reference应改用 API Reference PostHog 插件它会同时处理 API Reference 与内嵌 API Client 两个产品的分析无需分别接入。安装依赖插件基于posthog-js实现首先需要安装它npm install posthog-js快速开始最小可运行的接入示例在 API Client 的插件数组中加入PostHogClientPlugin传入项目 API Key 与 API Host 即可import { PostHogClientPlugin } from scalar/api-client/plugins/posthog const plugins [ PostHogClientPlugin({ apiKey: phc_your_project_api_key, apiHost: https://us.i.posthog.com, }), ]PostHogClientPlugin是一个工厂函数返回类型为ClientPlugin定义见 packages/oas-utils/src/helpers/client-plugins.ts它同时提供了on事件监听器与lifecycle生命周期钩子可无缝挂入 API Client 的插件系统on订阅事件总线上的全部事件通过bus.onAny转发用于按需捕获lifecycle.onInit/onConfigChange/onDestroy分别在客户端初始化、配置变更、销毁时执行负责 PostHog 实例的创建、启用/停用捕获与清理。配置项详解OptionTypeRequiredDescriptionapiKeystringYes你的 PostHog 项目 API Keyphc_前缀apiHoststringYesPostHog API 主机地址上报数据的端点uiHoststringNoPostHog UI 主机地址用于会话录制、问卷调查等功能的资源加载defaultsConfigDefaultsNoPostHog 的 defaults 版本标识从源码index.ts可以看到PostHogConfig类型与 README 表格一一对应uiHost与defaults均为可选配置只在提供时才会被透传给posthog-js的初始化参数。具体映射逻辑如下const instance ph.init( config.apiKey, { api_host: config.apiHost, ...(config.uiHost ? { ui_host: config.uiHost } : {}), ...(config.defaults ? { defaults: config.defaults } : {}), opt_out_capturing_by_default: true, }, scalar-api-client, )值得注意的两个细节实例命名空间ph.init的第三个参数是实例名称scalar-api-client这使多个产品如 API Reference 使用scalar-api-reference可以在同一页面共享 PostHog 而互不干扰默认关闭捕获初始化时强制opt_out_capturing_by_default: true随后插件根据 API Client 的telemetry配置决定是否调用opt_in_capturing()——这正是加载即启用与telemetry 开关两层控制的落点。事件上报与隐私保护白名单 字段提取插件并非把所有事件一股脑上报而是通过 sanitize-event-payload.ts 中的TRACKED_EVENTS白名单做两层过滤第一层事件白名单。每个事件要么映射到一个提取器extractor要么显式标记为undefinedopt-out。不在映射表中的事件会被静默丢弃。源码注释明确指出被标记为undefined的事件是刻意不追踪的例如auth:update:security-scheme-secrets安全方案密钥operation:update:requestBody:value请求体内容operation:upsert:parameter参数内容select:nav-item、analytics:on:loaded等这种设计有一个工程上的巧妙之处新事件加入事件总线后只要开发者没有有意识地把它放进白名单或显式标记 opt-outTypeScript 会直接报类型错误从而强制对每个新事件的追踪决策进行显式评审。第二层字段提取。对被追踪的事件只提取安全、非 PII的属性其余字段一律剥离。提取器基于scalar/helpers/object/get-value-at-path实现例如auth:update:selected-security-schemes提取meta.type认证方式类型如apiKey/bearercookie:upsert:cookie、environment:upsert:environment提取collectionType区分document还是workspaceui:download:document提取formatjson/yamlworkspace:update:active-proxy提取布尔值enabled当提取器返回的属性集合为空时插件只调用posthog?.capture(event)而不携带 properties避免上报一堆无意义的{}噪音。测试用例 sanitize-event-payload.test.ts 专门验证了即使事件被追踪也会剥离未知字段这一行为payload 中混入secret、body等敏感字段时最终只会上报collectionType。登录/登出与生命周期身份识别与数据清理插件对用户身份事件有专门处理见 index.tslog:user-login不会把登录事件本身作为普通事件捕获而是在 payload 携带uid时调用posthog.identify(uid, { email, teamUid })完成用户关联log:user-logout调用posthog.reset()清空当前用户上下文避免后续匿名事件与上一用户错误关联onDestroy插件销毁时同样调用reset()并置空实例引用确保组件卸载后不再上报。与 telemetry 配置联动运行时动态开关插件尊重 API Client 的telemetry配置选项并且在运行时动态响应配置变更onConfigChange(context) { if (!posthog) return if (context.config.telemetry false) { posthog.opt_out_capturing() } else { posthog.opt_in_capturing() } }telemetry未设置或非false初始化时即opt_in_capturing()开始上报telemetry: false初始化时保持 opt-out 状态不产生任何上报即使运行中改为falseonConfigChange也会立即停用捕获。这一行为在 posthog-plugin.test.ts 中有完整覆盖测试分别验证了初始化时不 opt-in、配置变更为false时opt_out_capturing被调用、配置恢复时opt_in_capturing被调用三种场景。在 API Reference 中使用一键覆盖两个产品如果你使用的是 API Reference它内嵌了 API Client请引入 packages/api-reference/src/plugins/posthog/index.ts 中的PostHogPlugin而不是直接使用PostHogClientPlugin。它的实现方式是组合内部创建一份PostHogClientPlugin(config)并在onInit时透传调用其onInit/onConfigChange/onDestroy同时以scalar-api-reference名称初始化一个 PostHog 实例并通过posthog.register({ product: api-reference })标记产品维度通过apiClientPlugins: [clientPlugin]把客户端插件注册给内嵌的 API Client。这样API Reference 与内嵌的 API Client 各自以product属性区分上报一份配置同时覆盖两个产品。README 中同样提示了这一点并指向该插件作为 API Reference 场景的正确入口。真实项目中的接入示例在 Scalar 官方客户端应用 projects/scalar-app/src/App.vue 中可以看到插件与请求脚本插件并列使用的真实形态const plugins [ requestScriptsPlugin(), PostHogClientPlugin({ apiKey: phc_3elIjSOvGOo5aEwg6krzIY9IcQiRubsBtglOXsQ4Uu4, apiHost: https://magic.scalar.com, uiHost: https://us.posthog.com, }), ]这个示例展示了两个实践要点uiHost与apiHost可以指向不同地址——apiHost负责数据上报uiHost负责会话录制/问卷等 UI 资源插件系统支持多插件共存PostHog 插件只是ClientPlugin接口的一个普通实现。测试与验证插件的每个关键行为都有 Vitest 测试背书可作为接入或二次开发时的行为契约posthog-plugin.test.ts验证生命周期钩子存在、初始化时注册product: api-client、telemetry 开关联动、白名单事件捕获、登录 identify/登出 reset、销毁 reset以及非白名单事件如auth:update:security-scheme-secrets、operation:update:requestBody:value绝不捕获sanitize-event-payload.test.ts验证各提取器在字段缺失、类型错误如meta.type为数字、collectionType为null时返回空对象而非抛错并验证TRACKED_EVENTS中每个被追踪事件都有提取器、每个 opt-out 事件都显式为 undefined、二者合计覆盖全部事件键的完整性约束。测试中还通过vi.mock(posthog-js)与vi.stubGlobal(window, globalThis)模拟浏览器环境侧面印证了该插件仅面向浏览器运行环境、且初始化时对typeof window undefined做了防御性判断SSR 场景下直接跳过初始化。小结接入路径与隐私心智模型为 Scalar API Client 接入 PostHog 的完整决策路径如下先判断使用场景独立 API Client 用PostHogClientPlugin内嵌于 API Reference 则用PostHogPlugin安装posthog-js用apiKeyapiHost初始化按需补充uiHost、defaults遵循默认不追踪不加载插件即零上报加载后可通过telemetry: false全局关闭且运行时动态生效信任白名单机制事件与字段都被显式过滤密钥、请求体、参数等敏感数据不会进入 PostHog任何新事件都必须经过显式的追踪决策。这套显式 opt-in 白名单 字段提取 生命周期清理的组合让分析能力的接入与数据隐私的保护在同一个插件内达成平衡无论是自托管 PostHog 还是接入官方云服务都可以直接复用本文的配置模式。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
