Ever Gauzy 中集成 PostHog：使用 @gauzy/plugin-posthog-ui 实现产品分析与埋点追踪

后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载导读本文以 packages/plugins/posthog-ui/README.md 为核心骨架系统讲解 Ever Gauzy 中面向 Angular 应用的产品分析插件gauzy/plugin-posthog-ui如何完成安装与初始化配置、如何实现事件/页面浏览/表单/错误/HTTP 请求等多维度追踪、如何使用指令在模板中零成本埋点并深入源码剖析其底层实现原理。读完本文你将掌握在 Ever Gauzy或任意 Angular 21 应用中接入 PostHog 的完整实战方案包括配置项的含义、服务 API 的选用策略以及测试与发布该插件库的方法。插件概述把 PostHog 的开放产品分析能力装进 AngularEver Gauzy 是一套开源的企业经营管理平台ERP/CRM/HRM/ATS/PM前端基于 Angular 构建。PostHog 则是开源的产品分析平台提供事件追踪、会话录制、功能开关Feature Flags、漏斗分析、错误监控等能力。gauzy/plugin-posthog-ui正是将两者桥接的 UI 插件——它封装了posthog-jsSDK以 Angular 惯用的模块、服务、指令、拦截器形式让 Gauzy 应用能够实时采集用户行为、功能使用情况与应用事件。从仓库实际使用情况看该插件已经在 Gauzy 主应用中被启用apps/gauzy/src/app/app.module.ts 中通过PostHogModule.forRoot(...)注入且 apps/gauzy/src/app/pages/settings/monitoring/monitoring.component.ts 提供了posthogEnabled、posthogKey、posthogHost、posthogFlushInterval等全局/租户级设置项说明它在 Gauzy 中既可用于开发环境调试也可在生产环境按租户配置启用。插件核心能力源自其 package.json 与 posthog.interface.ts包括事件追踪采集自定义事件与用户操作页面浏览分析基于 Angular Router 的自动页面浏览追踪用户识别跨会话识别与追踪个体用户会话录制录制用户会话供回放与分析功能开关在 Angular 应用中实现 Feature Flags 与 A/B 测试错误监控追踪前端错误与异常HTTP 请求追踪自动采集 API 调用及耗时指标表单追踪追踪表单提交与字段交互分组分析Group Analytics将用户归属到公司、团队或组织超级属性Super Properties设置跨事件持久化的属性SSR 兼容可在服务端渲染场景下安全使用。安装使用你偏好的包管理器安装插件及其核心依赖npm install gauzy/plugin-posthog-ui posthog-js # 或 yarn add gauzy/plugin-posthog-ui posthog-js根据 package.json 的声明该插件将posthog-js当前锁定^1.236.2作为直接依赖angular/common与angular/core21.0.7作为 peerDependenciesrxjs与tslib为运行依赖。因此你的项目应运行在 Angular 21 与 Node.js 22 环境engines声明并使用 Yarn 1.22 或 npm 进行依赖管理。配置基础配置PostHogModule.forRoot在主应用模块中导入PostHogModule并调用forRoot传入配置// app.module.ts import { NgModule } from angular/core; import { BrowserModule } from angular/platform-browser; import { PostHogModule } from gauzy/plugin-posthog-ui; import { environment } from ../environments/environment; NgModule({ declarations: [AppComponent], imports: [ BrowserModule, PostHogModule.forRoot({ apiKey: environment.posthogApiKey, apiHost: environment.posthogHost || https://app.posthog.com, // 可选配置 captureHttpEvents: true, options: { capture_pageview: false, // 页面浏览由 Router 接管处理 persistence: localStorage, session_recording: { enabled: environment.production } } }) ], bootstrap: [AppComponent] }) export class AppModule {}配置对象对应源码中的PostHogModuleConfig接口见 posthog.interface.ts除apiKey必填外还支持以下扩展配置配置项类型说明apiKeystring必填。PostHog 项目 API KeyoptionsPartialPostHogConfig透传给posthog-js的原生配置api_host、persistence、session_recording、bootstrap等debugboolean是否开启调试模式注入到POSTHOG_DEBUG_MODEtoken默认falserouteTracking{ excluded?, included? }路由追踪白/黑名单提供excluded时匹配路由不追踪提供included时仅匹配路由被追踪两者同时提供时excluded优先httpTracking{ captureResponseBodies?, excludeUrls?, additionalProperties? }HTTP 请求追踪配置见下文从 posthog.module.ts 的实现可以看到forRoot实际完成的初始化工作将PostHogService、PostHogServiceManager注册为 provider把配置注入POSTHOG_CONFIGtoken把config.debug || false注入POSTHOG_DEBUG_MODEtoken通过provideAppInitializer在应用启动阶段调用 posthog-init.factory.ts 完成初始化当options.capture_exceptions ! false时条件性地注册PostHogInterceptor到HTTP_INTERCEPTORS多 provider实现 HTTP 错误/请求自动追踪。需要注意的是初始化工厂对“占位 Key”做了防护当apiKey缺失或等于DOCKER_POSTHOG_KEYDocker 部署未配置环境变量时的占位值时直接返回初始化失败时也会捕获异常并resolve从而保证应用启动不会被 PostHog 阻塞——这与 apps/gauzy/src/app/app.module.ts 中对DOCKER_POSTHOG_KEY的告警逻辑一致。环境配置在环境文件中添加以下变量// environments/environment.ts export const environment { production: false, posthogApiKey: YOUR_POSTHOG_API_KEY, posthogHost: https://app.posthog.com // 或你的自托管实例地址 };Gauzy 主应用中对应的环境变量为POSTHOG_ENABLED、POSTHOG_KEY、POSTHOG_HOST见 app.module.ts。posthog-js的原生配置里api_host默认值为https://app.posthog.com若使用自托管 PostHog 实例请将其替换为你的实例地址源码见 posthog.service.ts。使用指南服务选择PostHogServiceManager 与 PostHogService插件提供两个服务层PostHogServiceManager高层 API推荐应用代码使用面向组件封装自动携带初始化状态检查、路由追踪与配置驱动行为PostHogService底层 API直接封装posthog-js的全部能力captureEvent、capturePageview、identify、alias、group、Feature Flags、会话录制、超级属性等并负责 SSR 安全仅在浏览器平台初始化与全局错误监听。两个服务都以providedIn: root注册见 posthog-manager.service.ts 与 posthog.service.ts可直接构造函数注入。基础事件追踪在组件中注入高层服务并调用trackEventimport { Component } from angular/core; import { PostHogServiceManager } from gauzy/plugin-posthog-ui; Component({ selector: app-example, template: button (click)trackButtonClick()Click Me/button }) export class ExampleComponent { constructor(private posthogManager: PostHogServiceManager) {} trackButtonClick() { this.posthogManager.trackEvent(button_clicked, { buttonName: example_button, section: homepage }); } }底层实现上trackEvent先做初始化检查isInitialized()再转发给posthogService.captureEvent后者调用posthog.capture(eventName, properties, options)可选sendInstantly参数控制是否立即发送源码见 posthog.service.ts。指令式事件追踪模板零成本埋点插件提供了 Angular 独立指令standalone directive可在模板中直接声明式埋点。[phTrack]指令支持click、mouseenter、focus三种事件类型也支持在组件初始化时捕获!-- 基础事件追踪 -- button [phTrack]signup_button_clicked [phProperties]{ location: header, variant: primary }Sign Up/button !-- 高级配置 -- button [phTrack]button_clicked [phProperties]{ buttonName: submit } [phOnInit]true [phEventType]click [phStopPropagation]true Submit /button指令实现见 posthog-track.directive.tsHostListener监听click/mouseenter/focus仅当phEventType与触发事件匹配时才上报phOnInit为true时在ngOnInit阶段立即上报一次phStopPropagation控制是否阻止事件冒泡。由于该指令已由PostHogModule统一 export只要导入模块即可直接使用。表单追踪phFormTrack指令自动采集表单提交与字段交互。以下示例追踪signup_form表单启用字段级交互追踪并排除敏感字段、开启值脱敏form phFormTrack [phFormName]signup_form [phTrackFields]true [phExcludeFields][password, credit-card] [phSanitizeValues]true (ngSubmit)onSubmit() input nameemail typeemail / input namepassword typepassword / button typesubmitSubmit/button /form表单指令的能力远不止 README 示例源码 posthog-form-track.directive.ts 揭示了完整输入参数与安全机制输入默认值说明phFormNameform表单名称标识phTrackFieldsfalse是否追踪单个字段的交互phExcludeFields[password, secret, token, credit, card]排除字段支持字符串包含匹配与RegExpphSanitizeValuestrue是否对字段值脱敏截断超过 100 字符的值phTrackFocus/phTrackBlur/phTrackChangefalse/false/true是否追踪焦点、失焦、变更事件phIncludeMetadatatrue是否附带field_id、field_required、field_max_length等元数据phFieldPrefix字段交互事件名的前缀如myform_field_change该指令自动上报三类事件组件初始化时的form_viewed携带表单名、id、action 与字段清单、提交时的form_submitted携带form_valid校验状态与全部字段数据、以及field_focus/field_blur/field_change字段交互事件。安全性方面做到了三层防护shouldExcludeField排除敏感字段名、shouldRedactFieldValue对password类型及password/secret/token/auth/key/credit/card/cvv/ssn/social等敏感模式强制脱敏为[REDACTED]、sanitizeFieldValue截断超长值。指令通过Renderer2.listen动态绑定字段监听器并在ngOnDestroy中统一清理避免内存泄漏。用户识别用户登录成功后调用identifyUserlogin(user) { // 认证成功后 this.posthogManager.identifyUser(user.id, { email: user.email, name: user.name, plan: user.subscriptionPlan, signupDate: user.createdAt }); }identifyUser底层转发到posthog.identify(distinctId, userProperties)见 posthog-manager.service.ts。若应用启动配置了options.bootstrap.distinctID初始化阶段会自动调用identifyUser完成身份绑定注销或切换账号时可调用resetUser()清空当前身份。功能开关Feature Flagsimport { Component, OnInit } from angular/core; import { PostHogServiceManager } from gauzy/plugin-posthog-ui; Component({ selector: app-feature, template: if (newFeatureEnabled) { h2New Feature/h2 !-- 功能内容 -- } }) export class FeatureComponent implements OnInit { newFeatureEnabled false; constructor(private posthogManager: PostHogServiceManager) {} ngOnInit() { this.newFeatureEnabled this.posthogManager.isFeatureEnabled(new-feature); } }高层服务还提供getFeatureFlagValueT(flagKey, defaultValue)获取带类型的开关值、reloadFeatureFlags()手动重载。值得注意的细节在initialize的setupConfigBasedBehaviors中见 posthog-manager.service.ts当options.advanced_disable_feature_flags ! true且未禁用首载时插件会自动调用reloadFeatureFlags()预拉取开关因此组件中调用isFeatureEnabled时开关通常已就绪。底层PostHogService还额外暴露了getFeatureFlags(keys: string[])批量取值、setFeatureFlagOverride(key, value)本地覆盖常用于测试对应posthog.featureFlags.override。分组分析Group Analytics将用户与组织/团队关联// 当用户加入或切换团队时 this.posthogManager.setGroup(company, company-id-123, { name: Acme Corp, industry: Technology, tier: Enterprise });底层对应posthog.group(groupType, groupKey, groupProperties)适合 Gauzy 这类多租户企业管理平台按公司、团队维度做聚合分析。错误追踪插件在浏览器环境下自动为window注册error与unhandledrejection监听器见 posthog.service.ts自动捕获全局 JS 异常附带source/lineno/colno定位信息与未处理的 Promise rejection统一以$exception事件上报。HTTP 错误则由PostHogInterceptor自动捕获。也可以手动上报业务错误try { // 某些有风险的操作 } catch (error) { this.posthogManager.trackError(error, { context: payment_processing, user_action: checkout }); }captureError会将error_message、error_type、error_stack等结构化信息一并上报见 posthog.service.ts。若希望完全关闭自动异常捕获可在options中设置capture_exceptions: false——这同时会阻止拦截器的注册见 posthog.module.ts。HTTP 请求追踪通过httpTracking配置可以控制 API 调用追踪的粒度posthog.interface.tsPostHogModule.forRoot({ apiKey: environment.posthogApiKey, httpTracking: { // 是否采集响应体谨慎可能含敏感数据默认 false captureResponseBodies: false, // 排除特定路由支持字符串与 RegExp excludeUrls: [/api/analytics, /\/reports\/\d/], // 随 API 事件附加的自定义属性 additionalProperties: { app: gauzy, env: production } } })拦截器 posthog.interceptor.ts 的实现要点对每个被拦截的请求用performance.now()记录开始时间剥离 query 参数后构造事件属性path、method、url、withCredentials并合并additionalProperties通过tap在响应成功时写入status、success200-399 区间判定与可选的脱敏responseBody出错时写入status/success: false/errorMessage/errorType/statusText在finalize中计算耗时duration毫秒统一上报api_request事件shouldSkipTracking依据excludeUrls决定是否放行不追踪sanitizeResponseBody以递归方式深度上限 10 层脱敏password/token/secret/key/auth/credit/card等敏感字段防止响应体泄露隐私。超级属性Super Properties注册随每个事件一起发送的全局属性// 在应用初始化时设置一次 this.posthogManager.register({ app_version: 1.2.3, theme: dark, locale: en-US });注意README 中的register在高层服务 API 表中未单列但底层PostHogService.register(properties, days?)对应posthog.register可指定保留天数另有registerOnce仅当属性未设置时写入、unregister(propertyName)注销单个超级属性。此外在initialize阶段若options.persistence ! memory即使用 localStorage 等持久化存储插件会自动注册app_version超级属性见 posthog-manager.service.ts。API 参考PostHogServiceManager高层服务方法描述initialize(config: PostHogModuleConfig)以配置初始化 PostHog返回是否成功trackEvent(eventName: string, properties?: object)追踪自定义事件trackPageView(url?: string, properties?: object)捕获页面浏览事件identifyUser(userId: string, properties?: object)识别用户resetUser()重置当前用户身份setGroup(groupType: string, groupKey: string, groupProperties?: object)将用户与分组关联isFeatureEnabled(flagKey: string)检查功能开关是否开启getFeatureFlagValueT(flagKey: string, defaultValue: T)获取功能开关值reloadFeatureFlags()从 PostHog 重载功能开关setUserProperties(properties: object)设置当前用户属性optInTracking()/optOutTracking()选择加入/退出追踪trackError(error: Error, properties?: object)带上下文追踪错误getPostHogInstance()获取原始 PostHog 实例用于高级操作startSessionRecording()手动启动会话录制高层服务几乎每个方法都先做isInitialized()守卫未初始化时安全返回便于在服务尚未就绪或 SSR 环境下调用而不抛错。PostHogService底层服务方法描述initialize(apiKey: string, config?: object)初始化 PostHog仅浏览器平台执行captureEvent(eventName: string, properties?: object, sendInstantly?: boolean)追踪自定义事件capturePageview(url?: string, properties?: object)捕获页面浏览captureError(error: Error, properties?: object)追踪错误或异常identify(distinctId: string, userProperties?: object, callback?: () void)识别用户alias(alias: string, distinctId?: string, callback?: () void)为用户创建别名group(groupType: string, groupKey: string, groupProperties?: object)将用户与分组关联reset()重置当前用户isFeatureEnabled(key: string, options: { send_event: boolean })检查功能开关getFeatureFlag(key: string, defaultValue?: any)获取功能开关值setFeatureFlagOverride(key: string, value: any)覆盖功能开关用于测试reloadFeatureFlags()重载功能开关getFeatureFlags(keys: string[])批量获取多个功能开关值startSessionRecording()/stopSessionRecording()启动/停止会话录制register(properties: object, days?: number)注册超级属性registerOnce(properties: object, defaultValue?: any, days?: number)仅当未设置时注册属性unregister(propertyName: string)注销超级属性getDistinctId()获取当前用户 distinct IDoptOut()/optIn()/isOptedOut()退出/加入追踪及状态查询setPersonProperties(properties: object)设置用户person属性setPersonPropertiesOnce(properties: object)仅当未设置时设置用户属性setPersonPropertiesForFlags(properties: object)为功能开关计算设置用户属性setGroupPropertiesForFlags(map: object, reload?: boolean)为功能开关计算设置分组属性captureDeadClick(element: Element, properties?: object)捕获无效点击$dead_click事件getInstance()获取原始 PostHog 实例指令指令/输入描述[phTrack]在用户交互时追踪事件[phProperties]随事件发送的属性[phOnInit]是否在组件初始化时立即捕获[phEventType]监听的事件类型click、mouseenter、focus默认 click[phStopPropagation]是否阻止事件冒泡phFormTrack追踪表单提交与字段交互[phFormName]被追踪表单的名称标识[phTrackFields]是否追踪单个字段交互[phExcludeFields]排除的字段[phSanitizeValues]是否对字段值脱敏[phTrackFocus]是否追踪字段焦点事件[phTrackBlur]是否追踪字段失焦事件[phTrackChange]是否追踪字段变更事件页面浏览与路由追踪原理插件默认将capture_pageview置为false见 posthog.service.ts页面浏览改由 Router 事件驱动以获得对 URL 与计时指标的更精细控制。setupRouteTracking订阅router.events在NavigationStart记录起始时间在NavigationEnd计算加载耗时并上报$pageview事件附带load_time_ms导航耗时、referrer、route重定向后的 URL与route_id匹配到的路由 path等属性posthog.service.ts。该逻辑在initialize成功后由PostHogServiceManager自动调用一次且通过内部标记_routeTrackingAttached保证只绑定一次。若需要通过routeTracking配置做路由级过滤excluded/included可在模块配置中提供实现上以excluded优先。测试forTesting 与单元测试插件内置测试支持在测试模块中导入即可获得不执行真实初始化的 mock 环境// test.module.ts import { PostHogModule } from gauzy/plugin-posthog-ui; NgModule({ imports: [PostHogModule.forTesting()] }) export class TestModule {}从 posthog.module.ts 的实现可见forTesting()以apiKey: test-key与空loaded回调提供POSTHOG_CONFIG并将POSTHOG_DEBUG_MODE置为true且不注册 HTTP 拦截器——这样组件测试中注入PostHogServiceManager不会触发网络请求。运行插件单元测试基于 Jest jest-preset-angularyarn nx test plugin-posthog-ui构建与发布构建库yarn nx build plugin-posthog-ui构建产物输出到dist/packages/plugins/posthog-ui。发布到 npm registrycd dist/packages/plugins/posthog-ui npm publish若需要在开发模式下持续构建可使用yarn nx build plugin-posthog-ui --configurationdevelopment --watch对应 package.json 中的lib:build、lib:build:prod、lib:watch脚本。在 Ever Gauzy 中的真实落地方式回到 Gauzy 主应用PostHog 的启用采用“环境变量 运行时设置”双通道依据 apps/gauzy/src/app/app.module.ts环境变量POSTHOG_ENABLED、POSTHOG_KEY、POSTHOG_HOST控制构建期的启用开关与默认连接参数POSTHOG_KEY为 Docker 占位值DOCKER_POSTHOG_KEY时给出告警且不初始化运行时在设置页的监控Monitoring模块中见 monitoring.component.ts管理员可按 Global 与 Tenant 两个层级保存posthogEnabled、posthogKey、posthogHost、posthogFlushInterval默认刷新间隔 10000ms从而实现多租户环境下的按需启停与独立配置。这一落地模式说明gauzy/plugin-posthog-ui不只是实验性的埋点封装而是 Gauzy 生产级产品分析链路中的正式组件你可以依据同样的模式在自己的 Angular 业务应用中接入把用户行为、漏斗转化、功能开关与前端错误统一收拢到 PostHog 一处分析。小结gauzy/plugin-posthog-ui将 PostHog 的开放分析能力封装成了 Angular 生态的标准形态模块级forRoot配置、双层级服务 API、声明式追踪指令、表单安全埋点、HTTP 拦截器、SSR 防护与测试支持一应俱全。无论是 Ever Gauzy 平台内按租户启用产品分析还是在其他 Angular 项目中快速落地事件追踪与 Feature Flags本文所覆盖的配置项、方法签名与源码实现细节都能直接指导你的实战落地。赞分享后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载相关推荐Ever Gauzy AI 集成 UI 插件gauzy/plugin-integration-ai-ui开发实践与源码解析Ever Gauzy AI 集成 UI 插件gauzy/plugin integration ai ui开发实践与源码解析 Ever® Gauzy™ 的后端前端企业应用MCP 服务Ever Gauzy 集成 Sentry 监控gauzy/plugin-sentry 错误追踪与可观测性实战指南Ever Gauzy 集成 Sentry 监控gauzy/plugin sentry 错误追踪与可观测性实战指南 本文以 Ever Gauzy 开源仓库中的后端前端企业应用MCP 服务在 Ever Gauzy 中集成 Activepiecesgauzy/plugin-integration-activepieces-ui 插件深度解析在 Ever Gauzy 中集成 Activepiecesgauzy/plugin integration activepieces ui 插件深度解析 导后端前端企业应用MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考