Google Analytics 第三方輕量最小化頁面腳本 Quick GA4 使用說明

頁面腳本 Quick GA4

Quick GA4（quick-ga4.js）是一個免費的 Google Analytics 第三方輕量最小化頁面腳本（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'
}

為 Quick GA4 設定對應的 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 } }
]

在 Quick GA4 中調整 Google Analytics 工作階段設定

Google Analytics 站點中的工作階段設定，不會影響 Quick GA4 腳本的執行結果，相反的，你需要在 Quick GA4 中調整工作階段的功能。__GA4__物件的session屬性（同樣是一個物件）對應了工作階段，session包含了以下內容。

timeout 屬性

timeout屬性用於設定 Google Analytics 工作階段的逾時時間，以秒為單位，預設1800秒。工作階段逾時後，新的使用者活動會產生新的工作階段。

engagementMin 屬性

engagementMin屬性用於設定 Google Analytics 互動工作階段計時器閾值，以秒為單位，預設10秒。工作階段的互動時間超過該閾值後，將被視為互動工作階段。

engagementType 屬性

engagementMin屬性用於設定計算互動時間的方式，預設為'focus'。當engagementMin被設定為'focus'時，只有頁面獲得焦點時才會統計互動時間，當engagementMin被設定為'visible'時，只有頁面可見時才會統計互動時間。

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

在 Quick GA4 中設定頁面載入事件 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' }
}

在 Quick GA4 中設定互動時間事件 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 }
}

在 Quick GA4 中設定捲動事件 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 }
}

在 Quick GA4 中設定外連點選事件 click

與 Google 官方 GA4 腳本的效果類似，Quick GA4 腳本會傳送出站連結的click點選事件，指向站點內的連結點選則不被統計。如果你不希望外連點選事件被觸發，可以將__GA4__物件event屬性的outbound屬性設定為null，或任何可以被視為false的值。

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

在 Quick GA4 中設定搜尋事件 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' }
}

在 Quick GA4 中設定檔案下載事件 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)$/ }
}

在 Quick GA4 中設定 Google Analytics 的代理轉送位址

如果站點大部分使用者所處的網路，無法正常存取 Google Analytics 伺服器，那麽收集 Quick GA4 從頁面傳送的事件將變得困難。遇到這種問題，你可能需要擁有一個用於轉送的代理服務，並將代理轉送的位址指派給__GA4__物件的url屬性，Quick GA4 會通過該屬性給出的位址來傳送相關的事件和資訊。

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

在 Quick GA4 中啟用 Google Analytics 偵錯模式

將__GA4__物件的debug屬性設定為true，即可開啟 Google Analytics 的偵錯模式，如下面程式碼所示。

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