측정 프로토콜은 성숙하고 최종적인 제품 상태에 도달했으며 지원 중단 계획 없이 계속 운영될 예정입니다. 하지만 기술 설정을 미래에 대비할 수 있도록 하려면 향후 데이터 수집 혁신을 위한 중앙 인프라인 Data Manager API를 사용하여 서버 간 이벤트 통합을 구축하는 것이 좋습니다.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Google 애널리틱스로 측정 프로토콜 이벤트 전송

이 가이드에서는 Google 애널리틱스 보고서에서 측정 프로토콜 이벤트를 확인할 수 있도록 Google 애널리틱스 측정 프로토콜 웹 및 앱 스트림 이벤트를 Google 애널리틱스 서버로 전송하는 방법을 설명합니다.

측정 프로토콜 요청에 필요한 식별자와 매개변수는 웹 스트림 또는 앱 스트림에 이벤트를 전송하는지에 따라 다릅니다.

웹 스트림 (일반적으로 gtag.js 또는 Google 태그 관리자로 계측됨)의 경우 요청 URL에서 measurement_id를 사용하고 JSON 본문에서 client_id를 사용하여 사용자 인스턴스를 식별합니다. client_id는 웹사이트의 Google 애널리틱스 태그에서 생성된 ID와 일치해야 합니다.
앱 스트림 (Firebase SDK로 계측됨)의 경우 요청 URL에서 firebase_app_id를 사용하고 JSON 본문에서 app_instance_id를 사용합니다. 이는 Firebase용 Google 애널리틱스 SDK에서 제공됩니다.

이 가이드에서는 두 시나리오의 예를 제공합니다.

스트림 유형별 주요 요청 구성요소

구성요소	웹 스트림 (gtag.js/GTM)	앱 스트림 (Firebase)
데이터 스트림 URL 매개변수	`measurement_id`	`firebase_app_id`
API 비밀번호 URL 매개변수	필수	필수
기기 ID JSON 본문 필드	`client_id`	`app_instance_id`

이 가이드에서 확인할 플랫폼을 선택하세요.

이 탭에는 Firebase용 Google 애널리틱스 SDK를 사용하여 앱 스트림의 사용자 활동과 관련된 서버의 이벤트를 전송하는 방법이 나와 있습니다. 이러한 요청에서는 firebase_app_id 및 app_instance_id을 사용한다는 점에 유의하세요.

기본 요건

측정 프로토콜을 사용하여 이벤트를 전송하려면 Google 애널리틱스 속성 또는 Firebase 프로젝트의 특정 식별자가 필요합니다.

API 비밀번호

api_secret는 요청을 인증하는 데 사용됩니다. 이 보안 비밀을 기밀로 유지하는 것이 중요합니다.

새 보안 비밀을 만들려면 다음 안내를 따르세요.

Google 애널리틱스로 이동하여 계정 및 속성으로 이동합니다.
왼쪽 하단에서 관리를 클릭합니다.
데이터 수집 및 수정에서 데이터 스트림을 클릭합니다.
웹 또는 앱 데이터 스트림을 선택합니다.
측정 프로토콜 API 비밀번호를 클릭합니다.
만들기를 클릭합니다.
보안 비밀의 닉네임을 입력하고 만들기를 클릭합니다.
보안 비밀 값을 복사합니다.
중요: api_secret은 비공개입니다. 웹사이트 또는 앱의 클라이언트 측 코드에 노출하지 마세요.
- 보안 위험: api_secret를 노출하면 승인되지 않은 당사자가 Google 애널리틱스 속성에 임의의 데이터나 스팸 데이터를 전송할 수 있으며, 이로 인해 보고가 손상될 수 있습니다.
- 올바른 사용: 측정 프로토콜은 주로 서버 측 또는 신뢰할 수 있는 환경 (예: 오프라인 시스템 또는 서버 간 통신)을 위해 설계되었습니다.
- 클라이언트 측 추적: 웹브라우저에서 직접 이벤트를 전송해야 하는 경우 Google 태그 (gtag.js) 또는 Google 태그 관리자를 사용합니다.
- Chrome 확장 프로그램: Manifest V3 Chrome 확장 프로그램의 경우 gtag.js와 같은 원격 코드를 로드할 수 없습니다. 이 경우 측정 프로토콜을 사용하는 것이 좋습니다. Chrome 확장 프로그램에서 Google 애널리틱스 사용을 참고하세요.

Firebase 앱 ID

firebase_app_id는 Firebase 앱을 식별합니다. app_instance_id와는 다릅니다.

Firebase 앱 ID를 찾는 방법은 다음과 같습니다.

Firebase Console에서 프로젝트를 엽니다.
프로젝트 개요 옆에 있는 설정 톱니바퀴 아이콘을 클릭하고 프로젝트 설정을 선택합니다.
일반 탭에서 내 앱 섹션으로 이동합니다.
특정 iOS 또는 Android 앱을 선택합니다.
App ID 값을 복사합니다.

요청 형식 지정

Google 애널리틱스 측정 프로토콜은 HTTP POST 요청만 지원합니다.

이벤트를 전송하려면 다음 형식을 사용하세요.

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

요청 URL 쿼리 매개변수에 다음을 제공해야 합니다 (이러한 값을 찾거나 만드는 방법에 관한 자세한 내용은 기본 요건 참고).

api_secret: 요청을 인증하는 API 비밀번호입니다.
firebase_app_id: 애플리케이션의 Firebase 앱 ID입니다.

측정 프로토콜의 경우 JSON POST 본문 형식으로 요청 본문을 제공해야 합니다. 예를 들면 다음과 같습니다.

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

모바일 앱의 고유한 설치를 식별하려면 요청 본문에 app_instance_id를 제공해야 합니다. 이는 앱 자체를 식별하는 firebase_app_id와는 다릅니다. app_instance_id 및 Firebase SDK를 사용하여 이를 검색하는 방법에 관한 자세한 내용은 app_instance_id 참고 문서를 참고하세요.

session_start는 예약된 이벤트 이름이지만 새 session_id를 만들면 session_start를 전송하지 않고도 새 세션을 만들 수 있습니다. 세션수를 집계하는 방법을 알아보세요.

직접 해 보기

다음은 여러 이벤트를 한 번에 전송할 때 사용할 수 있는 예입니다. 이 예에서는 tutorial_begin 이벤트와 join_group 이벤트를 Google 애널리틱스 서버로 전송하고, user_location 필드를 사용하여 지리적 정보를 포함하고, device 필드를 사용하여 기기 정보를 포함합니다.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

firebase_app_id의 형식은 플랫폼마다 다릅니다. Firebase 구성 파일 및 객체에서 애플리케이션 ID를 참고하세요.

타임스탬프 재정의

측정 프로토콜은 요청의 각 이벤트 및 사용자 속성에 대해 다음 목록에서 찾은 첫 번째 타임스탬프를 사용합니다.

이벤트 또는 사용자 속성의 timestamp_micros입니다.
요청의 timestamp_micros로,
측정 프로토콜이 요청을 수신한 시간입니다.

다음 예에서는 요청의 모든 이벤트와 사용자 속성에 적용되는 요청 수준 타임스탬프를 전송합니다. 따라서 측정 프로토콜은 tutorial_begin 및 join_group 이벤트와 customer_tier 사용자 속성에 requestUnixEpochTimeInMicros 타임스탬프를 할당합니다.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

다음 예에서는 요청 수준 타임스탬프, 이벤트 수준 타임스탬프, 사용자 속성 수준 타임스탬프를 전송합니다. 따라서 측정 프로토콜은 다음 타임스탬프를 할당합니다.

tutorial_begin 이벤트의 tutorialBeginUnixEpochTimeInMicros
customer_tier 사용자 속성의 customerTierUnixEpochTimeInMicros
requestUnixEpochTimeInMicros join_group 이벤트 및 newsletter_reader 사용자 속성

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

이전 이벤트 및 사용자 속성의 유효성 검사 동작

이벤트와 사용자 속성은 최대 72시간까지 이전 날짜로 설정할 수 있습니다. timestamp_micros 값이 72시간 전보다 이전인 경우 측정 프로토콜은 다음과 같이 이벤트 또는 사용자 속성을 수락하거나 거부합니다.

validation_behavior가 설정되지 않았거나 RELAXED로 설정된 경우 측정 프로토콜은 이벤트 또는 사용자 속성을 허용하지만 타임스탬프를 72시간 전으로 재정의합니다.
validation_behavior이 ENFORCE_RECOMMENDATIONS로 설정되면 측정 프로토콜에서 이벤트 또는 사용자 속성을 거부합니다.

Firebase용 Google 애널리틱스 SDK 또는 gtag.js에서 수집한 이벤트와 함께 조인하거나 처리하기 위해 측정 프로토콜을 사용하여 전송된 이벤트는 원래 클라이언트 측 이벤트 타임스탬프로부터 48시간 이내에 Google 애널리틱스에서 수신해야 합니다. 이 시간 이후에 수신된 이벤트는 특히 전환 기여 분석과 같은 목적으로 예상대로 처리되지 않을 수 있습니다.

제한사항

Google 애널리틱스로 측정 프로토콜을 전송하는 데는 다음 제한사항이 적용됩니다.

속성당 시간당 최대 1억 개의 전환 외 요청을 보낼 수 있습니다. 요청에 있는 이벤트 중 Google Ads의 전환이 있는 주요 이벤트가 없는 경우 요청은 전환이 아닌 요청입니다. 이 한도를 초과하면 측정 프로토콜에서 해당 시간의 남은 시간 동안 속성에 대한 모든 전환 외 요청을 자동으로 무시합니다.

핵심사항: 이 한도는 Google 애널리틱스 360 속성에는 적용되지 않습니다.
요청은 최대 25개의 이벤트를 포함할 수 있습니다.
이벤트는 최대 25개의 매개변수를 포함할 수 있습니다.
이벤트는 최대 25개의 사용자 속성을 포함할 수 있습니다.
사용자 속성 이름은 24자(영문 기준) 이하여야 합니다.
사용자 속성 값은 36자(영문 기준) 이하여야 합니다.
이벤트 이름은 40자(영문 기준) 이하여야 하고 영숫자 및 밑줄 문자만 사용할 수 있으며 알파벳으로 시작해야 합니다.
항목 매개변수를 포함한 매개변수 이름은 40자(영문 기준) 이하여야 하고 영숫자 문자 및 밑줄 문자만 사용할 수 있으며 알파벳으로 시작해야 합니다.
상품 매개변수 값을 포함한 매개변수 값은 표준 Google 애널리틱스 속성의 경우 100자(영문 기준) 이하여야 하고 Google 애널리틱스 360 속성의 경우 500자(영문 기준) 이하여야 합니다.

이 한도는 Google 태그 관리자의 해당 애널리틱스 세션 ID 및 애널리틱스 세션 번호 기본 변수에서 값을 제공하는 경우 session_id 및 session_number 매개변수에는 적용되지 않습니다.
항목 매개변수는 최대 10개의 맞춤 매개변수를 포함할 수 있습니다.
POST 본문은 130KB보다 작아야 합니다.
Google 애널리틱스로 전송된 앱 측정 프로토콜 이벤트는 앱 사용자의 Google Ads 검색 잠재고객을 채우지 않습니다.
일부 이벤트, 매개변수, 사용자 속성 이름은 예약되어 있으므로 사용할 수 없습니다. 자세한 내용은 예약된 이름을 참고하세요.

예약된 이름

측정 프로토콜에는 이벤트, 매개변수 또는 사용자 속성에 사용할 수 없는 여러 예약된 이름이 있습니다.

다음 이벤트 이름은 혼동을 일으키는 경우가 많습니다.

screen_view: 이 이벤트는 앱 스트림에만 허용됩니다. 웹 스트림의 경우 page_view을 대신 사용합니다.
ad_impression: 이 이벤트는 앱 스트림에만 허용됩니다.
in_app_purchase: 이 이벤트는 앱 스트림에만 허용됩니다. 웹 스트림의 경우 대신 purchase 이벤트를 사용하세요.

각 사용 사례의 추가 요구사항은 일반적인 사용 사례를 참고하세요.