측정 프로토콜 참조

개요

측정 프로토콜을 사용하여 Google 애널리틱스로 데이터를 전송하는 작업은 다음과 같이 두 부분으로 구성되어 있습니다.

1. 전송 - 데이터를 전송하는 위치와 방법
2. 페이로드 - 전송하는 데이터

이 문서에서는 전송 및 페이로드의 형식을 지정하는 방법을 설명합니다.

전송

URL 엔드포인트

다음 엔드포인트에 대한 HTTP POST 요청을 수행하여 측정 프로토콜을 통해 데이터를 전송합니다.

https://www.google-analytics.com/mp/collect

참고: 모든 데이터는 HTTPS를 통해 안전하게 전송되어야 합니다.

이벤트를 전송하려면 다음 POST 요청을 실행합니다.

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data>

• 요청의 BODY로, 페이로드를 참고하세요.

응답 코드

측정 프로토콜은 HTTP 요청이 수신된 경우 항상 2xx 상태 코드를 반환합니다. 측정 프로토콜은 페이로드 데이터의 형식이 잘못된 경우 또는 페이로드의 데이터가 잘못되었거나 Google 애널리틱스에서 처리되지 않은 경우 오류 코드를 반환하지 않습니다.

중요: 2xx 상태 코드를 받지 못한 경우 요청을 다시 시도하면 안 되고, HTTP 요청의 오류를 중단시키고 수정해야 합니다.

페이로드

Firebase gtag.js

측정 프로토콜 데이터를 사용하여 Google 애널리틱스로 데이터를 전송하는 작업은 다음과 같이 두 부분으로 구성되어 있습니다.

1. 쿼리 매개변수
2. JSON POST 본문

쿼리 매개변수

매개변수 이름	설명
api_secret	필수사항. Google 애널리틱스 UI를 통해 생성된 API Secret입니다. 새 보안 비밀을 만들려면 Google 애널리틱스 UI에서 다음과 같이 이동합니다. 관리 > 데이터 스트림 > 스트림 선택 > 측정 프로토콜 > 만들기 이러한 설정은 조직에서 비공개로 유지하는 것이 좋습니다. 측정 프로토콜을 클라이언트 측에 배포하는 경우, 과도한 스팸이 발생하지 않도록 api_secret을 정기적으로 순환해야 합니다.

JSON POST 본문

키	유형	설명
user_id	string	선택사항. 사용자의 고유 식별자입니다. 이 식별자에 관한 자세한 내용은 교차 플랫폼 분석용 User-ID를 참고하세요. user_id에는 utf-8 문자만 포함될 수 있습니다.
timestamp_micros	number	선택사항. 이벤트와 연결할 시간의 Unix 타임스탬프(단위: 마이크로초)입니다. 과거에 발생한 이벤트만 기록하도록 설정해야 합니다. 이 값은 user_property 또는 이벤트 타임스탬프를 통해 재정의할 수 있습니다. 이벤트는 속성의 시간대를 기준으로 최대 3일을 소급 적용할 수 있습니다. 이 값은 밀리초가 아닌 마이크로초 단위여야 합니다.
user_properties	object	선택사항. 측정에 대한 사용자 속성입니다. 자세한 내용은 사용자 속성을 참고하세요.
user_data	object	선택사항입니다. 사용자 제공 데이터 자세한 내용은 사용자 제공 데이터 가이드를 참고하세요.
consent	object	선택사항입니다. 요청의 동의 설정을 설정합니다. 자세한 내용은 동의 섹션을 참고하세요.
non_personalized_ads	boolean	선택사항입니다. 사용자의 데이터를 개인 맞춤 광고에 사용해서는 안 된다는 것을 나타내려면 true로 설정하세요. 사용하지 않음: 이 필드 대신 consent의 ad_personalization 필드를 사용하세요. Google 애널리틱스에서는 두 필드 중 하나를 허용하지만 ad_personalization 필드를 사용하는 것이 좋습니다.
events[]	array	필수사항. 이벤트 항목의 배열입니다. 요청당 최대 25개의 이벤트를 전송할 수 있습니다. 이벤트 참조에서 모든 유효한 이벤트를 확인하세요.
events[].name	string	필수사항. 이벤트 이름입니다. 이벤트 참조에서 모든 옵션을 확인하세요.
events[].params	object	선택사항. 이벤트의 매개변수입니다. 이벤트에서 각 이벤트에 대한 추천 매개변수를 참고하세요.

동의

consent 속성은 동의 유형 및 상태를 구성합니다. consent를 지정하지 않으면 Google 애널리틱스에서 클라이언트 또는 앱 인스턴스에 해당하는 온라인 상호작용의 동의 설정을 사용합니다.

키	유형	설명
ad_user_data	string	선택사항. 광고 목적으로 요청의 이벤트 및 사용자 속성에서 사용자 데이터를 Google에 전송하는 것에 대한 동의를 설정합니다. GRANTED 또는 DENIED 중 하나여야 합니다.
ad_personalization	string	선택사항. 사용자의 개인 맞춤 광고에 대한 동의를 설정합니다. GRANTED 또는 DENIED이어야 합니다.

맞춤 매개변수

사전 정의된 매개변수 외에도 측정 프로토콜 페이로드 내에 맞춤 사용자 범위, 이벤트 범위, 상품 범위 매개변수를 포함할 수 있습니다.

• 사용자 범위 맞춤 매개변수는 페이로드의 user_properties 객체에 포함할 수 있습니다.
• 이벤트 범위 맞춤 매개변수는 페이로드의 events[].params 객체에 포함할 수 있습니다.
• 상품 범위 맞춤 매개변수는 각 이벤트의 items 배열에 포함할 수 있습니다.

특정 이벤트의 권장 값

일부 이벤트에는 권장 매개변수가 있습니다. 지원되는 모든 이벤트의 권장 매개변수는 이벤트를 참고하세요.

예약된 이름

예약된 이벤트 이름

다음 이벤트 이름은 예약되어 있으므로 사용할 수 없습니다.

• ad_activeview
• ad_click
• ad_exposure
• ad_query
• ad_reward
• adunit_exposure
• app_clear_data
• app_exception
• app_install
• app_remove
• app_store_refund
• app_update
• app_upgrade
• dynamic_link_app_open
• dynamic_link_app_update
• dynamic_link_first_open
• error
• firebase_campaign
• firebase_in_app_message_action
• firebase_in_app_message_dismiss
• firebase_in_app_message_impression
• first_open
• first_visit
• in_app_purchase
• notification_dismiss
• notification_foreground
• notification_open
• notification_receive
• notification_send
• os_update
• session_start
• user_engagement

예약된 매개변수 이름

다음 매개변수 이름은 예약되어 있으므로 사용할 수 없습니다.

• firebase_conversion

또한 매개변수 이름은 다음으로 시작할 수 없습니다.

• _ (underscore)
• firebase_
• ga_
• google_
• gtag.

예약된 사용자 속성 이름

다음 사용자 속성 이름은 예약되어 있으므로 사용할 수 없습니다.

• first_open_time
• first_visit_time
• last_deep_link_referrer
• user_id
• first_open_after_install

또한 사용자 속성 이름은 다음으로 시작할 수 없습니다.

• _ (underscore)
• firebase_
• ga_
• google_