GA4 第三方轻量最小化页面脚本 Quick GA4 使用说明

页面脚本 Quick GA4

Quick GA4（quick-ga4.js）是一个免费的 Google Analytics（GA4）第三方轻量最小化页面脚本（JavaScript），他实现了官方 GA4 脚本所具备的主要实用功能，包括增强型衡量功能中的网页浏览量，滚动次数，出站点击次数，网站搜索，文件下载次数。

除了能够对以上功能进行常规配置，Quick GA4 还提供了额外的设置选项， 使得某些功能更具灵活性。比如，设置用于触发滚动事件的目标元素以及阈值，排除特定出站链接使他们不会触发出站点击事件，设置需要监视下载行为的文件链接。

不使用 gtag.js 向 Google Analytics 发送数据

使用 Quick GA4 后，你的页面不再需要包含 Google 代码（gtag.js）。由于 Google Analytics 并非gtag.js唯一针对的目标 ，因此他相对于analytics.js体积更大，在使用压缩格式后，gtag.js的传输大小可能在80kB至90kB之间（2024 年 2 月份期间的测试结果）。在网络速度不断提升的情况下，100kb的传输可能不是太大的问题，通过设置script元素的defer或async属性，gtag.js对页面加载的影响并不大。

使用页面脚本 Quick GA4

要在页面中使用 Quick GA4 脚本，只需添加加载quick-ga4.js的script元素，并编写配置 GA4 的 JavaScript 代码即可。你可以从 npm 或 GitHub 的相关项目中下载quick-ga4.js，然后上传至自己的服务器，以下是 Quick GA4 项目在 npm 和 GitHub 的地址。

quick-ga4 - npm

codebeatme/quick-ga4

当然，使用公共 CDN 上存储的quick-ga4.js也是可行的，以下地址可以通过 jsDelivr 载入最新版本的 Quick GA4 脚本。

cdn.jsdelivr.net/npm/quick-ga4

<script>
<!-- 这里需要替换为 GA4 配置代码 -->
</script>
<script defer="true" src="/js/quick-ga4.js"></script>

window['__GA4__'] = {
	id: 'G-XXXXXXXXXX'
}

设置对应的 Google Analytics 数据流

正如之前示例所演示的，通过把数据流的衡量 ID 赋值给__GA4__对象的id属性，Quick GA4 将可以为 Google Analytics 中特定的数据流提供信息。

如果希望指定多个数据流，那么可以采用数组的方式，他类似于id:['G-XXXXXXXXXX','G-XXXXXXXXXX']，在这种情况下，数据流是共享同一个 GA4 配置的，如果需要为不同数据流指定不同的 GA4 配置，那么可以将__GA4__对象改为数组，数组中的每一个元素对应一个独立的 GA4 配置。

window['__GA4__'] = [
	{ id: ['G-XXXXXXXXXX', 'G-XXXXXXXXXX'] },
	{ id: 'G-XXXXXXXXXX', event: { scroll: null } }
]

调整 Google Analytics 会话设置

Google Analytics 站点中的会话设置，不会影响 Quick GA4 脚本的运行结果，相反的，你需要在 Quick GA4 中调整会话的功能。__GA4__对象的session属性（同样是一个对象）对应了会话，session包含了以下内容。

timeout 属性

timeout属性用于设置会话的超时时间，以秒为单位，默认1800秒。会话超时后，新的用户活动会产生新的会话。

engagementMin 属性

engagementMin属性用于设置感兴趣会话计时器阈值，以秒为单位，默认10秒。会话的交互时间超过该阈值后，将被视为感兴趣会话。

engagementType 属性

engagementMin属性用于设置计算交互时间的方式，默认为'focus'。当engagementMin被设置为'focus'时，只有页面获得焦点时才会统计交互时间，当engagementMin被设置为'visible'时，只有页面可见时才会统计交互时间。

window['__GA4__'] = {
	// …
	session: { timeout: 900, engagementMin: 20, engagementType: 'visible' }
}

设置页面载入事件 page_view

通过__GA4__对象event属性（同样是一个对象）的pageView属性，你可以设置 Google Analytics 的页面载入事件page_view，该属性是一个表示page_view触发条件的字符串，默认为'*'（除了预渲染以外的任何页面载入形式都将触发page_view）。

pageView属性可以从以下项中选择或组合，不同的项之间使用,（或其他起到正则表达式\b作用的字符）进行分隔，对于想要排除的项，需要添加^。比如，'navigate,reload'表示选择navigate和reload两项，'*,^back_forward'表示选择back_forward之外的所有项。

navigate

navigate项表示当页面通过点击链接，地址栏输入 URL，提交表单操作载入时，触发page_view事件。

reload

reload项表示当页面通过刷新载入时，触发page_view事件。

back_forward

back_forward项表示当页面通过历史记录操作载入时，触发page_view事件。

*

*产生的效果是，除了预渲染以外的任何形式的页面载入都将触发page_view。

window['__GA4__'] = {
	// …
	event: { pageView: '*,^reload' }
}

设置交互时间事件 user_engagement

__GA4__对象event属性的userEngagement属性，用于表示触发 Google Analytics 交互时间事件的事件，默认为'beforeunload'（建议采用默认值），他表示在window的beforeunload事件中，触发交互时间事件user_engagement。如果你不希望将页面的交互时间发送至 Google 服务器，那么可以将userEngagement属性设置为null，或任何可以被视为false的值。

__GA4__对象trigger属性（同样是一个对象）的userEngagementMin属性，表示要触发user_engagement事件，当前页面需要存活的秒数，默认为1秒。假设页面在打开后的0.5秒被关闭，那么user_engagement事件无法被触发。

window['__GA4__'] = {
	// …
	trigger: { userEngagementMin: 3 }
}

设置滚动事件 scroll

__GA4__对象event属性的scroll属性，是指向某个滚动元素的 CSS 样式选择器，默认为'body'。scroll属性可以解决复杂页面设计带来的一些问题，当主要内容在页面的其他元素中溢出，导致body元素无法产生滚动条时（这种情况下，Quick GA4 以及 Google 官方的 GA4 脚本可能会百分百触发scroll事件），你可以指定具有滚动条的元素，成为用于判断是否触发scroll事件的目标元素。

如果你不希望滚动事件被触发，可以将scroll属性设置为null，或任何可以被视为false的值。

window['__GA4__'] = {
	// …
	event: { scroll: '#my-content' },
	trigger: { scrollPercentMin: 70 }
}

设置出站点击事件 click

与 Google 官方 GA4 脚本的效果类似，Quick GA4 脚本会发送出站链接的click点击事件，指向站点内的链接点击则不被统计。如果你不希望出站点击事件被触发，可以将__GA4__对象event属性的outbound属性设置为null，或任何可以被视为false的值。

window['__GA4__'] = {
	// …
	event: { outbound: [/xxx\.xxx/, /yyy\.yyy/] }
}

设置搜索事件 view_search_results

__GA4__对象event属性的viewSearchResults属性，用于设置触发搜索事件view_search_results的查询参数，查询参数之间使用,分隔，默认为'q,s,search,query,keyword'。当浏览器的 URL 出现指定的查询参数之一并具有有效值时，搜索事件将被触发。

如果你不希望搜索事件被触发，可以将__GA4__对象event属性的viewSearchResults属性设置为null，或任何可以被视为false的值。

window['__GA4__'] = {
	// …
	event: { viewSearchResults: 'key&color,size' }
}

设置文件下载事件 file_download

__GA4__对象event属性的fileDownload属性是一个正则表达式（或表示正则表达式的字符串），用于判断页面上哪些a元素应被视为下载文件的链接，默认为'(?<=\\.)(pdf|xlsx?|docx?|txt|rtf|csv|exe|key|pp(s|t|tx)|7z|pkg|rar|gz|zip|avi|mov|mp4|mpe?g|wmv|midi?|mp3|wav|wma)$'（针对文件扩展名）。

你可以尝试其他的正则表达式来匹配自己的下载链接，比如，/_download_/将匹配 URL 包含_download_的链接。

window['__GA4__'] = {
	// …
	event: { fileDownload: /\.(cs|py|js)$/ }
}

设置 Google Analytics 的代理转发地址

如果站点大部分用户所处的网络，无法正常访问 Google Analytics 服务器，那么收集 Quick GA4 从页面发送的事件将变得困难。遇到这种问题，你可能需要拥有一个用于转发的代理服务，并将代理转发的地址赋值给__GA4__对象的url属性，Quick GA4 会通过该属性给出的地址来发送相关的事件和信息。

window['__GA4__'] = {
	// …
	url: 'https://xxx.xxx/xxx/xxx'
}

启用 Google Analytics 调试模式

将__GA4__对象的debug属性设置为true，即可开启 Google Analytics 的调试模式，如下面代码所示。

window['__GA4__'] = {
	// …
	debug: true
}