[GA4] WebhookNotification 연동하기 - GCP 및 Slack 활용

GA4 Webhook Notification 연동하기

시작하기 Getting Started

GA4는 시간이 걸리는 작업에 대한 처리완료 시 GA4 Data API에 웹훅 알림(Webhook Notification)을 설정하여 지정한 웹훅 서버로 데이터 변경에 대한 알림을 보내는 기능을 제공합니다.

웹훅이란?

웹훅이란 데이터가 변경되었을 때 실시간으로 알림을 받을 수 있는 기능입니다. 웹 서비스의 이벤트 데이터를 전달하는 HTTP 기반 콜백 함수입니다. 특정 이벤트가 발생하면 웹훅이 클라이언트에게 이벤트 데이터를 보내요. 웹훅이라는 단어는 2007년에 Jeff Lindsay에 의해 처음 사용되었어요. HTTP 기반의 웹 특징과 훅(Hook) 기능을 합친 용어죠. 
(출처: 토스페이먼츠 개발자센터)

API 폴링과 웹훅의 차이점 (출처: 토스페이먼츠 개발자센터)

준비사항

• GA4 Data API 
• GCP Cloud Functions
• Slack API: Incoming Wehbhook

 

API 훑어보기

WebhookNotification은 audienceList API 속성에 추가하여 사용하면 됩니다. 웹훅 기능을 검증하기 위해v1alpha.properties.audienceLists.create에 Webhook 속성값을 추가하여 테스트를 진행하였습니다. 

properties.audienceLists REST API

WebhookNotification API 규격 상세

WebhookNotification 상세

• 적용가능 API: Data API > v1alpha > properties.audienceLists 또는 properties.recurringAudienceLists에 적용 가능
• Note: Google Analytics 리포트 데이터에 접근하기 위해서는 Data API를 사용해야 합니다. WebhookNotification 속성은 uri와 channelToken으로 구성됩니다.

JSON 포맷

{
  "uri": string,
  "channelToken": string
}

uri를 설정할 때 아래와 같은 특징 및 제약사항을 확인해야 합니다.

• 웹훅 알림을 받을 웹주소
• 웹훅 수신메시지는 POST request로 리턴됨
• sentTimestamp: 보낸 시간(UNIX microseconds). 재전송되었는지 확인할 때 사용
• HTTPS만 가능하며, 유효한 SSL 인증서가 있는 웹서버여야 함

Audience List API

HTTP Request

POST https://analyticsdata.googleapis.com/v1alpha/{parent=properties/*}/audienceLists

Path Parameter

properties값은 GA Admin > Property > Property Detail 메뉴에서 확인하세요. 위 {parent=properties/*}에 아래와 같은 형식으로 Property값을 추가하면 됩니다.

properties/262940150

Request

GA Admin API 조회에서 받아온 audience값을 Request audience값에 추가합니다. dimensionName은 deviceId로 추가합니다. uri에는 웹훅서버용으로 생성한 GCP Cloud Functions URL(https://us-central1-singular-XXXXXX.cloudfunctions.net/ga4-webhook)을 추가하였습니다. 

{
  "audience": "properties/262940150/audiences/5816450822",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "webhookNotification": {
    "uri": "https://us-central1-singular-XXXXXX.cloudfunctions.net/ga4-webhook"    
  }
}

Response

아래 리턴 예시에서 state가 CREATING으로 리턴된 것을 볼 수 있습니다. 작업이 완료되면 state가 ACTIVE로 변경되어 한번 더 웹훅이 리턴됩니다. 

{
  "name": "operations/262940150pa2597756",
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/262940150/audienceLists/2597756",
    "audience": "properties/262940150/audiences/5816450822",
    "audienceDisplayName": "GA Data API 연동하기 - 1. Overview 페이지 방문자",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2024-04-20T11:02:28.096195246Z",
    "rowCount": 0,
    "percentageCompleted": 0,
    "webhookNotification": {
      "uri": "https://us-central1-singular-XXXXXX.cloudfunctions.net/ga4-webhook"
    }
  }
}

 

GCP 설정

Cloud IAM 설정

Webhook uri 부분 가이드에 따라 역할을 부여합니다.

Webhook 가이드 내용
In Cloud IAM, you will need to grant the service account permissions to the Cloud Run Invoker (roles/run.invoker) & Cloud Functions Invoker (roles/cloudfunctions.invoker) roles for the webhook post request to pass Google Cloud Functions authentication.

가이드 내용과 같이 google-analytics-audience-export@system.gserviceaccount.com에 Cloud Run 호출자, Cloud Functions 호출자 역할을 추가했습니다. (아래 그림)

Cloud Function 생성

Cloud Functions 함수 만들기

• 환경: 2세대(2nd gen)
• Function name: ga4-webhook
• Region: us-central1(선택)
• Trigger
  • Trigger type: HTTPS
  • Authentication: Require authentication 선택

Cloud Functions 생성

웹훅 코드 추가

웹훅 코드 추가

샘플코드

package.json

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "axios": "1.6.7"
  }
}

index.js

const functions = require('@google-cloud/functions-framework');
const http = require('axios');

functions.http('ga4webhook', async (req, res) => {
  // res.send(`Hello ${req.query.name || req.body.name || 'World'}!`);
  const postback_body = req.body;
  console.log(`postback: ${JSON.stringify(req.body)}`);

  const response = await http.post('<Slack Incoming Webhook URL>',{
    text: JSON.stringify(req.body)
  });
  console.log(`response: ${response.data}`);
  res.json({ "result": response.data }).status(200);
});

 

Slack 앱 생성 및 웹훅 주소 가져오기

앱 생성

• https://api.slack.com/apps에서 슬랙앱을 생성합니다.
• GA4웹훅을 슬랙으로 받기 위해 GA4 Report 앱을 생성하였습니다.

슬랙 앱 생성

Incoming Webhook 주소 확인

생성된 앱을 클릭하면 아래와 같이 Incoming Webhooks 메뉴를 확인할 수 있습니다. 아래 Webhook URL에 있는 URL을 복사하여 GCP Cloud Functions post URL에 추가합니다.

Cloud Functions 웹훅 수신결과

Slack Incoming Webhook 수신결과

아래 그림과 같이 CREATING 상태에 대한 웹훅이 먼저 수신되고, 데이터처리가 완료된 후 ACTIVE 상태에 대한 웹훅이 추가로 수신된 것을 확인할 수 있습니다.

Reference

WebhookNotification

WebhookNotification  |  Data API  |  Google for Developers

Data API - proeperties.audeinceLists

REST Resource: properties.audienceLists  |  Data API  |  Google for Developers

Axios module - POST requests

POST Requests | Axios Docs

슬랙 API: 앱 생성

Slack API: Applications | Slack