Python을 활용한 Google Analytics 잠재고객 목록 API 활용 - 1. Overview

 

Python을 활용한 Google Analytics 잠재고객 목록  API 활용 - 1. Overview

GA4의 잠재고객은 앱, 웹 등에 방문한 유저를 세그먼트화하는 기능을 제공합니다. GA4에서 제공하는 Dimension, Metrics, Events 등으로 유저를 분류하여 비즈니스 목적에 따라 사용자를 구분한 다음 Google Ads등에 연결하여 리마케팅 광고 등에 활용하게 됩니다. 잠재고객기능을 활용하기 위해서는 우선 Admin에서 제공하는 잠재고객 생성을 참고하시기 바랍니다.

---

GA4 잠재고객 목록(GA4 Audience List)

잠재고객과 잠재고객 목록의 구분

잠재고객과 잠재고객 목록 기능은 API상으로 완전히 구분되어 있습니다. 잠재고객을 생성하기 위해서는 Admin API를 활용하여야 하고, 생성된 잠재고객에 실 유저목록을 생성하기 위해서는 Data API에 있는 잠재고객목록 기능을 활용하여 합니다.

• 잠재고객: Google Analytics Admin API
• 잠재고객 목록: Google Analytics Data API
  • 잠재고객 목록 API는 v1alpha version에서만 지원합니다.

 

GA4 잠재고객 목록 API 테스트(Testing GA4 AudeinceList API )

1. [Admin API] 잠재고객관리 목록조회 - Method: properties.audiences.list

잠재고객목록을 생성하기 위해서는 audience에 넣을 값이 필요합니다. audience값을 획득하기 위해서 우선 Admin API - 잠재고객관리 Audience 리스트 조회를 실행해야 합니다.

HTTP request

GET https://analyticsadmin.googleapis.com/v1alpha/{parent=properties/*}/audiences

요청 파라미터에 /properties/<your-ga4-property-id>를 입력합니다.

잠재고객관리 - audience list 조회

 

HTTP response

응답시 audiences 배열에 각 잠재고객 그룹별 메타정보(name, displayName, description, membershipDurationDays, adsPersonalizationEnabled)가 반환됩니다. GA4 Data API를 통해 잠재고객그룹별 고객목록을 생성하기 위해서는 아래 빨간색 화살표에 표시된 URI Path를 사용하게 됩니다. 따라서 다음에 소개할 audienceList API 호출 시 이 Path값을 복사하여 요청값에 사용하게 되는 점을 꼭 기억하시기 바랍니다.

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

잠재고객관리API - 잠재고객별 메타데이터 응답

2. [Data API] 잠재고객목록 생성 - Method: properties.audienceLists.create

HTTP request

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

Request parameter에 properties/<your-ga4-property-id> 형식으로 Path를 완성합니다. Request body에는 audience와 생성할 dimension(측정기준)을 입력해야 합니다. audience 영역에는 앞서 잠재고객관리 리스트 API에서 반환된 name값을 활용합니다.

• audience
  • 잠재고객관리에 생성한 목록이 여러개일 경우 실제 고객목록을 생성하고자 하는 잠재고객그룹의 name을 확인하여 해당 값을 API 요청시 추가하면 됩니다.
• dimension: 구글 문서에 있는 측정기준 가이드를 참고합니다.(링크)
  • deviceId: 브라우저 또는 모바일에서 생성한 UUID
  • userId: 클라이언트 서비스에서 사용하는 실제 유저ID(일종의 고객번호)

아래 API에서는 deviceId만 고객목록으로 생성하도록 설정하였습니다.

잠재고객 목록 생성 API 테스트

 

아래 응답값을 보면 response object로 처리내용이 반환된 것을 확인할 수 있습니다. 고객목록생성은 비동기이므로 state가 "CREATING"으로 되어있는 것을 볼 수 있습니다. 즉 아직 고객목록파일을 생성하는 중이므로 일정시간 이후 state가 ACTIVE로 변경되었었는지 확인할 수 있습니다. Google Analytics4 뿐 아니라 대부분의 분석솔루션은 목록조회시 비동기처리 방식을 취하며, state변경여부를 확인한 다음 실제 데이터 목록을 조회하거나 다운로드 받을 수 있는 점을 참고하시면 됩니다. 

잠재고객목록 생성 응답

3. [Data API] 잠재고객목록 단일그룹 조회 - Method: properties.audienceLists.get

생성된 잠재고객목록 중 특정 잠재고객그룹을 조회합니다. 이전 API에서 반환된 name값에 해당하는 properties/262940150/audienceLists/1659415를 request parameter의 Path값으로 활용하면 됩니다. 

HTTP Request

GET https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/audienceLists/*}

잠재고객 단일그룹 조회요청

HTTP Response

잠재고객 단일그룹 조회결과

4. [Data API] 사용자의 잠재고객목록 검색 - Method: properties.audienceLists.query

단일 잠재고객그룹의 사용자가 포함된 데이터를 조회할 경우 query API endpoint를 호출하여야 합니다.

HTTP request

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

쿼리조회시에는 시작행의 행수과 반환할 행의 개수를 지정할 수 있습니다. limit은 미지정시 10,000개의 행이 반환되고, 최대 250,000개 행이 반환됩니다. 또한 행의 총개수가 limit보다 적은 경우에는 총개수만큼만 반환됩니다.

HTTP response

쿼리API 응답시 아래와 같이 실제 고객목록(audienceRows)가 함께 조회되는 것을 확인할 수 있습니다.

단일잠재고객 쿼리결과 - rowCount 78건

단일잠재고객 쿼리결과 - audienceRows

5. [Data API] 잠재고객 목록 조회 - Method: properties.audienceLists.list

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

HTTP request

매개변수로 properties/<your-ga4-property-id>를 입력합니다.

HTTP response

응답값으로 audienceList 배열이 반환된 것을 확인할 수 있습니다. Admin API의 잠재고객목록조회기능과 달리 Data API의 잠재고객목록조회시에는 잠재고객생성에 필요한 필터조건은 반환되지 않으며 대신 state, creationQuotaTokensCharged(할당량토큰), rowCount 등이 반환된 점을 확인할 수 있습니다.

지금까지 잠재고객목록 생성과 관련된 생성, 특정잠재고객목록/전체잠재고객목록 조회, 사용자 잠재고객 목록 검색(=유저목록포함 조회) API를 살펴보았습니다. 다음 포스트에서는 Python 라이브러리를 활용하여 API기능을 구현해 보도록 하겠습니다.

---

참고

잠재고객 생성

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

잠재고객 목록 생성

잠재고객 목록 기본사항  |  Google Analytics Data API  |  Google for Developers

Admin API - 잠재고객관리 목록조회

Method: properties.audiences.list  |  Google Analytics Admin API  |  Google for Developers