开发工具【免费下载链接】react-gaReact Google Analytics Module项目地址https://gitcode.com/gh_mirrors/re/react-ga点击查看免费下载react-ga 是一个专为 React 前端项目设计的 Google AnalyticsUniversal AnalyticsJavaScript 模块它以一套简洁、可读性强的 API 封装了原生analytics.js帮助开发者标准化跨项目的埋点实现。本文将围绕initialize、pageview、event、timing、outboundLink等核心 API 展开完整讲解并结合仓库源码src/core.js、类型定义types/index.d.ts与测试用例说明每个接口的底层调用链、参数校验规则与多 tracker 机制让读者能够直接在自己的 React 项目中落地一套可维护的 GA 埋点方案。react-ga 是什么react-ga 是一个用于在基于 React 构建的网站或应用中引入 Google Analytics 埋点代码的 JavaScript 模块。它内部并不依赖任何 React 运行时但最初是作为 Mozilla 基金会多个 React 站点的统一 GA 埋点方案而编写的。它只兼容Universal Analyticsanalytics.js不支持旧版的ga.js实现见 README.md 开头说明。与原生 Google Analytics 库相比react-ga 的 API 略显“啰嗦”但这正是其设计取向用更具可读性的方法签名降低工程师理解与维护埋点代码的成本。例如原生写法ga(send, pageview, /about)在 react-ga 中对应ReactGA.pageview(/about)语义更加清晰。安装使用 npm 安装npm install react-ga --save使用 bower 安装bower install react-ga --save注意要使用OutboundLink组件需要 React 0.14.0。当前仓库的 peerDependencies 声明为react: ^15.6.2 || ^16.0 || ^17 || ^18见 package.json可直接对齐现代 React 项目。快速开始npm 方式初始化并上报页面浏览量import ReactGA from react-ga; ReactGA.initialize(UA-000000-01); ReactGA.pageview(window.location.pathname window.location.search);bower 方式script 标签引入通过 bower 以 script 标签引入时会在全局作用域暴露ReactGA变量!-- The core React library -- script srchttps://unpkg.com/react15.5.0/dist/react.min.js/script !-- The ReactDOM Library -- script srchttps://unpkg.com/react-dom15.5.0/dist/react-dom.min.js/script !-- ReactGA library -- script src/path/to/bower_components/react-ga/dist/react-ga.min.js/script script ReactGA.initialize(UA-000000-01, { debug: true }); /script运行仓库自带 Demo仓库的 demo 目录提供了一套基于 react-router 的可运行示例。克隆本仓库后依次执行npm install npm start然后打开 http://localhost:8080 并按页面提示操作。Demo 需要你拥有自己的 TrackingID 才能看到真实数据。启动脚本定义在 package.json 的start字段webpack-dev-server --config demo/webpack.config.js --hot --inline入口与构建配置见 demo/index.jsx 与 demo/webpack.config.js。ReactGA.initialize一切埋点的起点initialize(gaTrackingID, options)是所有跟踪函数生效的前提。任何其他跟踪 API 在初始化之前调用都不会记录数据。初始化时传入的值会经过校验并最终发往ga(create, ...)调用。单 tracker 初始化示例ReactGA.initialize(UA-000000-01, { debug: true, titleCase: false, gaOptions: { userId: 123 } });多 tracker 初始化示例ReactGA.initialize( [ { trackingId: UA-000000-01, gaOptions: { name: tracker1, userId: 123 } }, { trackingId: UA-000000-02, gaOptions: { name: tracker2 } } ], { debug: true, alwaysSendToDefaultTracker: false } );从源码 src/core.js 可以看到初始化过程的底层行为initialize首先根据testMode决定是否进入测试模式非测试模式下如果standardImplementation ! true会调用loadGA(options)注入 analytics.js 脚本见 src/utils/loadGA.js然后通过addTrackers逐个处理 tracker数组形式的配置会逐项调用_initialize(config.trackingId, config)并校验每个配置必须是对象_initialize中若传入gaOptions则调用internalGa(create, gaTrackingID, options.gaOptions)否则回退为internalGa(create, gaTrackingID, auto)当options.useExistingGa为true时_initialize会直接返回跳过window.ga()的 create 调用适用于你已经手动执行过 GA 初始化脚本的场景。initialize 参数说明值说明gaTrackingIDString。必填。GA 跟踪 ID形如UA-000000-01。缺失时会打印gaTrackingID is required in initialize()警告并中止见 initialize.test.jsoptions.debugBoolean。可选。设为true时会在控制台输出额外的反馈信息同时loadGA会改为加载调试版脚本analytics_debug.jsoptions.titleCaseBoolean。可选。默认true。设为false时发送给 GA 的字符串不做 Title Case 转换options.gaOptionsObject。可选。GA 在create阶段可配置的字段如userId、name、siteSpeedSampleRate等对应类型定义 GaOptionsoptions.gaAddressString。可选。如果自行托管analytics.js可在此指定脚本 URLoptions.alwaysSendToDefaultTrackerBoolean。可选。默认true。设为false且使用多 tracker 时事件不会发送给默认 trackeroptions.testModeBoolean。可选。默认false。开启测试模式详见下文「Test Mode」options.standardImplementationBoolean。可选。默认false。开启后按 Google 官方期望的方式加载 GA详见下文「Standard Implementation」options.useExistingGaBoolean。可选。跳过window.ga()的 create 调用假设你已经手动执行过options.redactEmailBoolean。可选。默认true。启用后会将疑似邮箱地址的字符串在「Event Category」与「Event Action」中脱敏替换options.onerrorFunction。可选。loadGA注入的 script 标签发生加载错误时的回调见 src/utils/loadGA.js关于 siteSpeedSampleRate 的实用提示如果你在 GA 报表中拿不到 Page Timings 数据可能需要在gaOptions中加入siteSpeedSampleRate: 100。默认情况下 GA 只上报 1% 的命中hit设置为 100 后会将 100% 的命中发送到 Google Analytics。这一字段同样收录在 types/index.d.ts 的GaOptions中。多 tracker 的底层实现多 tracker 的实现集中在_gaCommand见 src/core.js当传入trackerNames数组时会为每个 tracker 名生成name.command前缀的调用例如baz.send同时根据_alwaysSendToDefaultTracker决定是否向默认 tracker 发送。这一点在 event.test.js 中有明确断言初始化两个 tracker 后调用ReactGA.event(..., [baz])最终依次产生ga(create, foo, auto)、ga(create, bar, { name: baz })、默认send以及ga(baz.send, {...})共 4 次调用。核心 API 详解以下所有方法均可选传入trackerNamesArrayString作为额外需要执行命令的 tracker 列表。ReactGA.set(fieldsObject, [trackerNames])用于在 Google Analytics 中设置自定义维度custom dimensions等字段值。ReactGA.set({ dimension14: Sports });或指定 trackerReactGA.set({ userId: 123 }, [tracker2]);值说明fieldsObjectObject。例如{ userId: 123 }。若缺失、非对象或为空对象会分别输出对应警告见 src/core.jstrackerNamesArray。可选。需要执行该命令的额外 tracker 列表ReactGA.pageview(path, [trackerNames], [title])发送页面浏览命中。ReactGA.pageview(/about/contact-us);或指定 tracker 与页面标题ReactGA.pageview(/about/contact-us, [tracker2]);值说明pathString。例如/get-involved/other-ways-to-help。缺失时警告path is required in .pageview()trim 后为空字符串时警告path cannot be an empty string in .pageview()见 pageview.test.jstrackerNamesArray。可选。额外执行该命令的 tracker 列表titleString。可选。例如Other Ways to Help会被写入send字段对象的title属性底层实现见 src/core.jspageview会先对 path 做trim处理然后以{ hitType: pageview, page: path, ...extraFields }为字段对象调用_gaCommand(trackerNames, send, fieldObject)。与 react-router 集成仓库 demo/app/withTracker.jsx 提供了一个与 react-router 配合的高阶组件HOC范例在componentDidMount中首次上报在UNSAFE_componentWillReceiveProps中比较路由变化后再次上报上报时先ReactGA.set({ page })再ReactGA.pageview(page)。将其包裹在路由组件外即可实现每个页面切换自动上报具体用法见 demo/app/Router.jsx。ReactGA.modalview(modalName, [trackerNames])模态框Modal视图在 UX 上常等同于一次页面浏览但 URL 并没有变化因此无法触发标准的 GA pageview。例如「联系我们」弹窗在站内任意页面都可能出现此时应使用modalview记录。ReactGA.modalview(/about/contact-us);值说明modalNameString。例如login、read-terms-and-conditions底层实现见 src/core.js会先移除开头的/利用 removeLeadingSlash.js再拼装为/modal/${modalName}路径以 pageview 方式发送。因此传入/valid最终也会上报为/modal/valid对应测试见 modalview.test.js。ReactGA.event(args, [trackerNames])跟踪页内交互是理解任何交互型 Web 产品使用情况的关键event用于记录不触发 URL 变化的行为。ReactGA.event({ category: User, action: Created an Account }); ReactGA.event({ category: Social, action: Rated an App, value: 3 }); ReactGA.event({ category: Editing, action: Deleted Component, label: Game Widget }); ReactGA.event({ category: Promotion, action: Displayed Promotional Widget, label: Homepage Thing, nonInteraction: true });值说明args.categoryString。必填。事件的顶层分类如User、Navigation、App Editing。缺失时警告args.category AND args.action are required in event()args.actionString。必填。行为描述如Clicked Delete、Added a component、Deleted accountargs.labelString。可选。对相关动作更精确的标注如动作Added a component时可用组件名Survey、Heading、Button作为 labelargs.valueInt。可选。为事件记录数值如评分、分数等。非数字会警告Expected \args.value arg to be a Number.见 event.test.jsargs.nonInteractionBoolean。可选。若事件不是用户交互触发而是代码自动触发如页面加载时应标记为nonInteraction以避免扭曲跳出率数据args.transportString。可选。命中发送的传输机制合法值包括beacon、xhr、image。非字符串或不在合法值列表内会分别告警见 src/core.js自定义维度与指标event还支持在参数对象中直接携带dimension1~dimension20与metric1~metric20前缀的字段类型定义见 types/index.d.ts。源码 src/core.js 会按前缀过滤这些字段并并入发送的字段对象ReactGA.event({ category: Test, action: Send Test, dimension1: foo, metric1: 1 });对应断言见 event.test.js。ReactGA.timing(args, [trackerNames])用于测量 AJAX 请求、资源加载等耗时区间通过 analytics.js 库发送 User Timing 命中。ReactGA.timing({ category: JS Libraries, variable: load, value: 20, // 单位毫秒 label: CDN libs });等价于原生 GA 命令ga(send, timing, JS Libraries, load, 20, CDN libs);值说明args.categoryString。必填。用于将所有 User Timing 变量归类到逻辑分组args.variableString。必填。被记录的变量名称args.valueInt。必填。要上报的已流逝毫秒数。源码要求必须为数字否则警告args.category, args.variable AND args.value are required in timing() AND args.value has to be a number见 src/core.jsargs.labelString。可选。为报表中的 User Timing 可视化增加灵活性ReactGA.ga()通过该方法可以直接访问原始的ga函数用于调用ReactGA尚未封装的ga.js特性。注意走这条路径时ReactGA不会做任何参数校验所有校验都被绕过。带参数调用ReactGA.ga(send, pageview, /mypage);不带参数调用返回ga对象var ga ReactGA.ga(); ga(send, pageview, /mypage);从源码看src/core.jsga()在收到参数时会经由internalGa转发并在debug模式下输出调用日志无论是否带参数最终都会返回window.ga。internalGa还承担了三重分发逻辑src/core.js测试模式下改写测试 API 记录非浏览器环境下返回falsewindow.ga未定义时警告必须先调用ReactGA.initialize或手动加载 Google Analytics。ReactGA.outboundLink(args, hitCallback, [trackerNames])用于跟踪跳转到外部 URL 的链接包括 OAuth 2.0 登录流程中的跳转。声明式的替代方案是使用OutboundLink组件见下一节。ReactGA.outboundLink( { label: Clicked Create an Account }, function () { console.log(redirect here); }, [tracker2] );值说明args.labelString。必填。外链指向的目标描述可以是 URL 或字符串hitCallbackfunction。react-ga 的实现考虑到了 GA 服务器宕机或被广告拦截器拦截的情况使用 250ms 超时作为兜底trackerNamesArrayString。可选。额外执行该命令的 tracker 列表250ms 兜底超时的实现细节源码 src/core.js 展示了这套安全机制hitCallback前注册一个 250ms 的setTimeoutsafetyCallback同时在发给 GA 的字段对象中注入hitCallbackclearableCallbackForGA后者会先清除定时器再通过safetyCallbackCalled标记防止回调被触发两次。即使 GA 完全不可用setTimeout(hitCallback, 0)也会保证应用流程继续。对应测试覆盖了「250ms 内 GA 响应」「超过 250ms」「GA 不可用」等多种场景见 outboundLink.test.jsx。OutboundLink组件外链可以直接作为 React 组件使用事件标签会自动发送给 react-gavar ReactGA require(react-ga); render() { return ( div ReactGA.OutboundLink eventLabelmyLabel tohttp://www.example.com target_blank trackerNames{[tracker2]} My Link /ReactGA.OutboundLink /div ); }值说明eventLabelString。必填。外链指向的目标描述可以是 URL 或字符串toString。必填。链接目标 URLtargetString。可选。要在新标签页打开则设为_blanktrackerNamesArrayString。可选。额外执行该命令的 tracker 列表组件实现见 src/components/OutboundLink.jshandleClick会区分普通点击同窗口且无 Ctrl/Shift/Meta 键且非中键与新标签页点击——普通点击先preventDefault等待跟踪命中完成后再跳转target_blank时会自动追加relnoopener noreferrer若已有自定义rel则追加在其后对应断言见 OutboundLink.test.jsx。组件通过 src/index.js 将trackLink静态方法替换为Defaults.outboundLink从而把点击事件与核心跟踪逻辑接通。bower 使用场景下同样使用ReactGA.OutboundLink组件。ReactGA.exception(args, [trackerNames])异常跟踪对应 GA 的 exception tracking 命中。ReactGA.exception({ description: An error occurred, fatal: true });值说明args.descriptionString。可选。对发生事件的描述args.fatalboolean。可选。若为致命异常则设为true源码 src/core.js 中exception会构造{ hitType: exception, exDescription, exFatal }字段对象其中fatal非布尔值会输出\args.fatal must be a boolean. 警告。ReactGA.plugin.require(name, [options], [trackerName])请求加载 GA 插件。ReactGA.plugin.require(localHitSender, { path: /log, debug: true });值说明nameString。必填。插件名。注意非官方 analytics.js 插件必须已在页面其他位置提供optionsObject。可选。插件实例化时传给构造函数的初始化对象trackerNameString。可选。指定时命令会以trackerName.require形式下发见 src/core.jsReactGA.plugin.execute(pluginName, action, [actionType], [payload])对指定插件执行action并携带 payload。ReactGA.plugin.execute(ecommerce, addTransaction, { id: jd38je31j, revenue: 3.50 });也可以用四个参数同时传递actionType与payloadReactGA.plugin.execute(ec, setAction, purchase, { id: jd38je31j, revenue: 3.50 });底层会将命令组装为pluginName:action形式并根据参数数量决定ga(command)、ga(command, payload)或ga(command, actionType, payload)三种调用形态见 src/core.js。Test Mode为单元测试而生开启测试模式后所有 GA 调用都不会真正发送而是被记录到ReactGA.testModeAPI.calls数组中方便在测试中直接断言调用序列。// 这段应放在测试的 setup 中 ReactGA.initialize(foo, { testMode: true }); // 这段放在被测组件/JS 中 ReactGA.ga(send, pageview, /mypage); // 这段用于断言调用是否正确 expect(ReactGA.testModeAPI.calls).toEqual([ [create, foo, auto], [send, pageview, /mypage] ]);底层实现见 src/utils/testModeAPI.jsga会把每次调用的参数序列 push 进gaCalls数组并暴露resetCalls()供测试间清理。对应测试 test/utils/testMode.test.js 完整复现了上面的断言流程。仓库其余功能测试也大量采用这种模式例如 event.test.js、pageview.test.js均在jest.mock(../../src/utils/loadGA)基础上以 spy 捕获window.ga调用这是理解本仓库测试写法的关键入口。Standard Implementation按 Google 官方方式加载若想按 Google 官方标准方式加载 analytics.js而非由 react-ga 动态注入可在 HTML 中预先放置官方加载脚本!-- Google Analytics -- script (function (i, s, o, g, r, a, m) { i[GoogleAnalyticsObject] r; (i[r] i[r] || function () { (i[r].q i[r].q || []).push(arguments); }), (i[r].l 1 * new Date()); (a s.createElement(o)), (m s.getElementsByTagName(o)[0]); a.async 1; a.src g; m.parentNode.insertBefore(a, m); })( window, document, script, %htmlWebpackPlugin.options.analyticsURL%, ga ); ga(create, UA-XXX-X, auto); ga(send, pageview); /script !-- End Google Analytics --随后初始化 react-ga 并开启standardImplementation: true// 这段应放在 setup 中 ReactGA.initialize(UA-XXX-X, { standardImplementation: true });由 src/core.js 可见standardImplementation为true时会跳过loadGA(options)的动态加载避免与页面中已有的官方脚本重复注入。从 1.x 升级到 2.x可以安全升级到 2.x没有破坏性变更。主要新增特性是底层ga函数现在通过ReactGA.ga属性暴露当你需要ReactGA暂时未支持的原生函数时可直接使用。基于此官方建议将导入的变量命名为ReactGA而非ga以区分 ReactGA 包装层与原始ga函数。开发与测试环境准备node.jsnpm安装依赖npm install可选依赖npm install react^15.6.1 prop-types^15.5.10运行测试npm test该命令实际执行cross-env BABEL_ENVtest jest --envjsdom --coverage见 package.json以 jsdom 环境运行并生成覆盖率报告npm run test:watch可进入监听模式。类型声明测试可通过npm run test:types执行tsc -p ./types/tsconfig.json针对 types/react-ga-tests.ts验证。TypeScript 支持仓库在 types/index.d.ts 提供了完整类型声明涵盖InitializeOptions、GaOptions、EventArgs含dimension1~dimension20、metric1~metric20、TimingArgs、Plugin、TestModeAPI、OutboundLinkProps等并声明了initialize针对单 tracker 字符串与多 tracker 数组的两种重载types/index.d.ts。package.json中types字段指向该文件TypeScript 项目引入react-ga后可直接获得智能提示与编译期校验。小结react-ga 以initialize为入口通过set、pageview、modalview、event、timing、exception、outboundLink与plugin等 API 覆盖了 Universal Analytics 埋点的绝大多数场景并以testMode、debug、redactEmail、250ms 兜底超时等机制解决了可测试性、可调试性与数据安全等工程问题。若需要查阅各 API 的完整参数与源码实现可分别对照 README.md、src/core.js 与 types/index.d.ts仓库 test 目录下的功能测试则是理解每个 API 实际调用形态的最佳参考。赞分享开发工具【免费下载链接】react-gaReact Google Analytics Module项目地址https://gitcode.com/gh_mirrors/re/react-ga点击查看免费下载相关推荐3分钟上手用Markdown轻松搞定PPTmd2pptx工具深度解析3分钟上手用Markdown轻松搞定PPTmd2pptx工具深度解析 场景引入被PPT折磨的技术人 又要做PPT——这句话是否让你瞬间血压升高技术开发工具超曲率空间、差分隐私与结构熵SocialED前沿社交事件检测算法HyperSED与HISEvent揭秘超曲率空间、差分隐私与结构熵SocialED前沿社交事件检测算法HyperSED与HISEvent揭秘 SocialED 是一个专为 社交事件检测Socialucide-react 使用指南在 React 应用中集成 Lucide 开源图标库lucide react 使用指南在 React 应用中集成 Lucide 开源图标库 导读 Lucide 是一个由社区驱动的开源图标库也是 Feather前端UI组件设计系统上一篇Windows 12网页版终极指南如何在浏览器中优雅处理运行时错误下一篇Microsoft.UI.Xaml数据网格控件高级数据展示与编辑功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考