使用 Measurement Protocol 將應用程式事件傳送至 GA4

1. 簡介

上次更新時間:2021 年 6 月 8 日

建構項目

在本程式碼研究室中,您將瞭解如何使用 Measurement Protocol 將外部事件傳送至 GA4。

本程式碼研究室假設您已有應用程式導入 Google Analytics for Firebase。如要瞭解與 Google Analytics for Firebase 整合的方式,請先參閱此程式碼研究室。如要瞭解如何使用 Firebase 建構應用程式,請參閱「Firebase Android Codelab 打造友善即時通訊」。

課程內容

  • 首次撥打 MP 電話的步驟
  • 瞭解呼叫所需的參數
  • 傳送測試通話並進行驗證
  • 在 Python 中建構範例指令碼來發出呼叫

軟硬體需求

  • 您的 Android 或 iOS 應用程式
  • 任何要進行變更的 IDE
  • GA4 帳戶
  • 選用 - Python 開發環境 (或 Colab)

2. 收集必填欄位

在 GA4 中建立 API 密鑰

前往 GA4 並建立新的 API 密鑰,方法是前往「管理」>「資料串流」>選擇直播 >Measurement Protocol >建立

6e4afca63054d291.png

c9e9ccd2ffba98eb.png

e714cd969fca4a4d.png

你可以提供任何暱稱,系統會在通話中顯示密鑰值,供你在通話中使用

如果您不確定如何存取 GA4,可以前往 Firebase 專案,依序點選「專案設定」>「專案設定」>「整合 >按一下 Google Analytics 並點選「管理」畫面應該會顯示 Google Analytics 連結,您也可以直接從該連結前往

73b4d77a57eddfba.png

收集 app_instance_id

您可以使用下列任一方法收集 app_instance_id。

  1. 使用 BigQuery Export
  2. 在應用程式原始碼中以原生方式擷取

以下將詳細說明上述兩種方法

  1. 使用 BigQuery Export

如果您已啟用 BigQuery 匯出 功能,可以按照以下步驟操作。

  • 登入 Firebase
  • 前往「專案設定」>整合 >BigQuery
  • 按一下「在 BigQuery 中查看」資料集附近

注意: 只有在啟用切換鈕約 24 到 48 小時後,才能使用資料集

63d061088b622961.png

  • 在 BigQuery 中,您可以查看資料表中的 user_pseudo_id。這是您可以在呼叫中使用的 app_instance_id

4b1b80bdc2884581.png

  1. 在應用程式原始碼中以原生方式擷取

如果您的應用程式是以 Java 建構,則可以使用類似方法擷取 app_instance_id

 FirebaseAnalytics.getInstance(this).getAppInstanceId().addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
            if (task.isSuccessful()) {
                String user_pseudo_id = task.getResult();
            }
        }
    });

如果是 Kotlin,您可以嘗試下列程式碼

Thread {
   Firebase.analytics.appInstanceId.addOnSuccessListener { user_pseudo_id ->
       Log.d("Firebase", "user_pseudo_id using appInstanceId is $user_pseudo_id")
       /*
       Store the value to your server or do something with the retrieved id
        */
   }
}.start()

如果您有 iOS 應用程式,可以在 Swift 中使用下列應用程式

let user_pseudo_id = Analytics.appInstanceID()
print("user_pseudo_id = \(user_pseudo_id)")
/*
Store the value to your server or do something with the retrieved id
*/

下列連結會因基礎架構而異

3. 建立呼叫

您可以使用 GA4 中的事件建構工具建立呼叫範例。(您需要登入並啟用 Cookie)。確認切換按鈕已設為「firebase」

fd78d961f3e48238.png

請務必填寫下列欄位

  • api_secret - 先前已在 GA4 中建立
  • firebase_app_id - 如要取得這項資訊,請依序前往「管理」>「資料串流」>選擇串流方式。如下所示

19801c8e5cb29222.png

  • app_instance_id - 您已擷取此值
  • 不一定要指定 user_id。目前可留空
  • 類別 - 變更為「自訂」,並填入您選擇的任何事件名稱 (請勿使用任何自動收集的事件)。使用「test_from_codelab」

54cce53df64d697.png

您也可以點選下方按鈕,選擇提供事件參數和/或使用者屬性

16a8f531a3894021.png

填寫完畢後,畫面上應該會顯示類似下方的內容,且會出現「驗證事件」按鈕

475801f25c3caf26.png

進入該頁面後,請按一下 [驗證事件],按鈕以橘色標明。系統應會在下方顯示訊息,指出活動有效,您應該會看到 [傳送至 Google Analytics] 的按鈕。此時,如果事件出現無效,這項工具會告訴您發生問題的確切欄位,方便您修正問題並重試

23e4e6800705b4aa.png

您現在可以點選按鈕,該按鈕應會向 GA4 傳送測試事件

4. 在 GA4 中驗證事件

傳送事件後,您就可以前往 GA4 帳戶查看「即時」事件。您應該會看到

994b51ca46bb1973.png

事件可能需要約 24 小時才會從即時資料檢視傳到實際的事件報表分頁,因此如果您沒有在一般事件報表中看到這類情況,也請不用擔心!

如果遇到任何問題或差異,建議您前往這裡查看 Measurement Protocol 的已知限制

5. 建立 Python 指令碼

測試完畢後,您可以檢查 API 呼叫和事件承載,以 Python (或任何您選擇的語言) 建構類似架構來發出這項呼叫。然後,即可按照所需頻率排定時程並運作。在這個部分,您可以使用任何支援 Python 的 IDE,或直接使用不需要在裝置上安裝的 Google Colab 筆記本

回到 GA4 事件建立工具,就會看到端點如下所示

POST /mp/collect?firebase_app_id=XXXX&api_secret=XXXX 
HTTP/1.1
Host: www.google-analytics.com

事件酬載如下

{
  "app_instance_id": XXXX,
  "non_personalized_ads": false,
  "events": [
    {
      "name": "test_from_codelab",
      "params": {
        "test_param": "test_123"
      }
    }
  ]
}

您可以使用類似下方的文字,將這些內容翻譯成 Python

import requests
import json
url = "https://www.google-analytics.com/mp/collect?firebase_app_id=XXXX&api_secret=XXXX"
payload = {
  "app_instance_id": XXXX,
  "non_personalized_ads": False,
  "events": [
    {
      "name": "test_from_codelab",
      "params": {
        "test_param": "test_123"
      }
    }
  ]
}
r = requests.post(url,data=json.dumps(payload),verify=True)
print(r.status_code)

使用正確的值執行這項作業後,應該也會在 GA4 中看到事件即時反映。

6. 恭喜

恭喜!您已成功在 GA4 中使用 Measurement Protocol。現在,您可以建立強大的解決方案架構,向 Google Analytics 傳送更有意義的資料,並提升行銷和業務分析成效。為充分發揮這項功能的效益,我們也建議您連結至 Google Ads,將這些事件匯入為轉換。如需詳細操作說明,請參閱本程式碼研究室的步驟 6。為進行轉換追蹤,Google Ads 只會顯示最近 60 天內,從 Firebase SDK 收集的廣告識別碼或裝置 ID 相關聯的資料。請注意,此 API 仍為 Alpha 版 API。請務必詳閱這裡 所列的限制,瞭解全面推出前應解決的限制

您已瞭解

  • 如何收集與媒體通話相關的正確變數
  • 如何傳送及驗證測試事件
  • 如何建立用於傳送媒體呼叫的指令碼