Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 앱을 선택합니다.
앱 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를 사용하여 이를 검색하는 방법에 대한 자세한 내용은 앱 인스턴스 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
join_group 이벤트 및 newsletter_reader 사용자 속성의 requestUnixEpochTimeInMicros

{
  "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 애널리틱스로 측정 프로토콜을 전송하는 데는 다음 제한사항이 적용됩니다.

요청은 최대 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 이벤트를 대신 사용하세요.

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