Python을 활용한 Google Analytics Admin API 잠재고객 연동 - 1. 목록조회

Python을 활용한 Google Analytics Admin API 잠재고객 연동 - 1. 목록조회

 

Google Analytics Admin API 소개

Admin API

Google Analytics Admin API는 프로그래매틱 방식으로 GA4 설정을 변경하거나 조회할 수 있도록 기능을 제공합니다. 해당 API는 GA4만 호환 가능하며 범용 애널리틱스(Universal Analytics 또는 UA)와는 연동되지 않습니다. 

주요 연동 기능 

• 새 계정 프로비저닝(Provision new accounts)
• 계정관리(Manage accounts)
• 속성관리(Manage proeperties)
• 스트림관리(Manage Streams)
• 전환이벤트관리(Manage conversion events)
• 측정기준 관리(Manage Custom Dimensions)
• 측정항목 관리(Manage Custom Metrics)
• 잠재고객 관리(Manage Audiences): 이 API 엔드포인트는 Google Analytics Data API(GA4) v1alpha의 audienceLists와 다릅니다. audienceLists는 실제 잠재고객 리스트를 생성하는 기능이며, 잠재고객 관리 API를 통해 잠재고객 ID를 받아온 다음 호출이 가능합니다.

이번 포스트에서는 '잠재고객 관리' API 연동에 대해서만 다룰 예정입니다. 각 기능별 API 엔드포인트 활용방법은 구글 공식문서를 참고하시기 바랍니다.

---

잠재고객 연동기능 개발(Integrate Admin API - Property Audience)

잠재고객 연동을 위해 Admin API에서 제공하는 API Endpoint를 살펴보고, 잠재고객 생성 및 API 연동규격, 실제 Python Code 테스트를 진행합니다.

 

잠재고객 Rest API

잠재고객 Rest API는 아래와 같이 5개의 엔드포인트를 제공합니다.

Audience Rest API
archive	속성(Property)에서 잠재고객 보관처리
create	잠재고객 생성
get	단일 잠재고객 조회
list	속성(Property)에 등록된 잠재고객 리스트 조회
patch	속성(Property)에 등록한 잠재고객 업데이트

 

잠재고객 설정하기

• 잠재고객 설정은 Admin > Property > Audiences 메뉴에서 설정합니다.
• New audience
  • New audience를 클릭하여 신규 잠재고객 조건을 설정할 수 있습니다.
  • 저는 특정페이지 방문자, 7-day inactive users라는 잠재고객 설정을 추가하였습니다.

Audiences 잠재고객 추가하기

---

 

잠재고객 목록 조회하기(Get property audience) - list API

속성 내 잠재고객 API는 Rest API v1alpha에 있습니다. 공식문서에 v1beta와 구분되어 있는 점을 참고하시기 바랍니다. List API 조회 시 parent에 속성ID를 Path Parameter로 입력하여 조회합니다.

Request

HTTP

GET https://analyticsadmin.googleapis.com/v1alpha/properties/[YOUR_PROPERTY_ID]/audiences?key=[YOUR_API_KEY] HTTP/1.1

Authorization: Bearer [YOUR_ACCESS_TOKEN]
Accept: application/json

cURL

curl \
  'https://analyticsadmin.googleapis.com/v1alpha/properties/[YOUR_PROPERTY_ID]/audiences?key=[YOUR_API_KEY]' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --compressed

Javascript

<script src="https://apis.google.com/js/api.js"></script>
<script>
  /**
   * Sample JavaScript code for analyticsadmin.properties.audiences.list
   * See instructions for running APIs Explorer code samples locally:
   * https://developers.google.com/explorer-help/code-samples#javascript
   */

  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/analytics.edit https://www.googleapis.com/auth/analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    gapi.client.setApiKey("YOUR_API_KEY");
    return gapi.client.load("https://analyticsadmin.googleapis.com/$discovery/rest?version=v1alpha")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.analyticsadmin.properties.audiences.list({
      "parent": "properties/[YOUR_PROPERTY_ID]"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: "YOUR_CLIENT_ID"});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

 

Response body

먼저 Audience JSON 구조를 확인해 보면 다음과 같습니다.

audiences

{
  "audiences": [
    {
      object (Audience)
    }
  ],
  "nextPageToken": string
}

audience object

{
  "name": string,
  "displayName": string,
  "description": string,
  "membershipDurationDays": integer,
  "adsPersonalizationEnabled": boolean,
  "eventTrigger": {
    object (AudienceEventTrigger)
  },
  "exclusionDurationMode": enum (AudienceExclusionDurationMode),
  "filterClauses": [
    {
      object (AudienceFilterClause)
    }
  ]
}

 

실제 응답값

GA4 UI 속성 내 잠재고객 목록과 같이 총 4개의 audiences 배열이 리턴되었습니다. 

{
  "audiences": [
    {
      "name": "properties/<property_id>/audiences/<specific_audience_id>",
      "displayName": "All Users",
      "description": "All users",
      "membershipDurationDays": 540,
      "adsPersonalizationEnabled": true
    },
    {
      "name": "properties/<property_id>/audiences/<specific_audience_id>",
      "displayName": "Purchasers",
      "description": "Users who have made a purchase",
      "membershipDurationDays": 540,
      "adsPersonalizationEnabled": true
    },
    {
      "name": "properties/<property_id>/audiences/<specific_audience_id>",
      "displayName": "7-day inactive users",
      "description": "Users who were once active, but have not been active for the last 7 days",
      "membershipDurationDays": 30,
      "adsPersonalizationEnabled": true,
      "filterClauses": [
        {
          "clauseType": "INCLUDE",
          "simpleFilter": {
            "scope": "AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
            "filterExpression": {
              "andGroup": {
                "filterExpressions": [
                  {
                    "orGroup": {
                      "filterExpressions": [
                        {
                          "eventFilter": {
                            "eventName": "session_start",
                            "eventParameterFilterExpression": {
                              "andGroup": {
                                "filterExpressions": [
                                  {
                                    "orGroup": {
                                      "filterExpressions": [
                                        {
                                          "dimensionOrMetricFilter": {
                                            "fieldName": "event_count",
                                            "numericFilter": {
                                              "operation": "EQUAL",
                                              "value": {
                                                "int64Value": "0"
                                              }
                                            },
                                            "inAnyNDayPeriod": 7
                                          }
                                        }
                                      ]
                                    }
                                  }
                                ]
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      ]
    },
    {
      "name": "properties/<property_id>/audiences/<specific_audience_id>",
      "displayName": "GA Data API 연동하기 - 1. Overview 페이지 방문자",
      "membershipDurationDays": 30,
      "adsPersonalizationEnabled": true,
      "filterClauses": [
        {
          "clauseType": "INCLUDE",
          "simpleFilter": {
            "scope": "AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
            "filterExpression": {
              "andGroup": {
                "filterExpressions": [
                  {
                    "orGroup": {
                      "filterExpressions": [
                        {
                          "dimensionOrMetricFilter": {
                            "fieldName": "pageTitle",
                            "stringFilter": {
                              "matchType": "CONTAINS",
                              "value": "Google Analytics Data API(GA4) 연동하기 - 1. Overview"
                            }
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      ]
    }
  ]
}

---

Python 연동하기

가상환경설정

# 가상환경설정이 되어 있지 않은 경우 if you don't install the virtualenv
pip install virtualenv

# 가상환경 설정(프로젝트 루트): venv이란 이름으로 가상환경 생성
virtualenv venv

# 가상환경 실행(Mac/Linux)
source venv/bin/activate

python module 설치하기

# 가상환경 활성화 후 모듈 설치
pip install google-analytics-admin

Analytics User 권한 확인

service account 권한을 확인합니다. Admin API의 경우, 등록된 계정의 권한이 Admin이어야 합니다. Edit 권한 또는 Read 권한만 있을 경우 권한오류가 리턴될 수 있습니다.

GCP 프로젝트에 Google Analytics Admin API 추가

Enable API - Google Analytics Admin API

 

파이썬 코드

Rest API에서 살펴본 것과 같이 Module도 admin_v1alpha를 선언합니다. 아래 코드에서는 비동기처리를 위해 AnalyticsAdminServiceAsyncClient를 사용하였고, types에 실제 API 호출시 사용할 함수(ListAudiencesRequest)도 추가하였습니다.

run_ga4_admin.py

from google.oauth2 import service_account

from google.analytics.admin_v1alpha.services.analytics_admin_service import AnalyticsAdminServiceAsyncClient, AnalyticsAdminServiceClient
from google.analytics.admin_v1alpha.types import (
    RunAccessReportRequest,
    GetAudienceRequest,
    ListAudiencesRequest,
    AccessDateRange,
)
    
credentials = service_account.Credentials.from_service_account_file(
    'service_account.json'
)

async def get_admin_audience(property_id="<YOUR_PROPERTY_ID>"):
    client = AnalyticsAdminServiceAsyncClient(credentials=credentials)

    request = ListAudiencesRequest(
        parent=f"properties/{property_id}"
    )
    response = await client.list_audiences(request)

    print("Report result:")
    print(response._response)

main.py

import asyncio
from run_ga4_admin import get_admin_audience

def main():
    asyncio.run(get_admin_audience())


if __name__ == "__main__":
    main()

코드 응답결과 확인

GA4 admin API 파이썬 연동 결과

API 연동 결과, UI에 등록된 잠재고객 목록이 잘 리턴되었습니다.

마치며

프로그래머틱 방식으로 GA4 잠재고객 기능을 조회하는 기능을 살펴보았습니다. 잠재고객 목록 외에 특정 잠재고객 그룹 조회 및 생성, 변경 기능도 순차적으로 살펴보도록 하겠습니다.

---

참고자료

Google 애널리틱스 Admin API 개요

Google 애널리틱스 Admin API 개요  |  Google Analytics Admin API  |  Google for Developers

REST Resource: properties.audiences

REST Resource: properties.audiences  |  Google Analytics Admin API  |  Google for Developers

AnalsyticsAdminService

AnalyticsAdminService — google-analytics-admin documentation

GitHub - googleapis/python-analytics-admin

GitHub - googleapis/python-analytics-admin