이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

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

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

요청 형식 지정

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

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

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

요청 URL에 다음을 포함해야 합니다.

api_secret: Google 애널리틱스 UI에서 생성된 API 비밀번호입니다.

새 비밀번호를 만들려면 관리자 > 데이터 스트림 > 스트림 선택 > 측정 프로토콜 > 생성으로 이동합니다.

measurement_id: 스트림과 연결된 측정 ID로, 관리자 > 데이터 스트림 > 스트림 선택 > 측정 ID 아래의 Google 애널리틱스 UI에서 찾을 수 있습니다.

measurement_id는 스트릠 ID가 아닙니다.

전체 참조를 보려면 쿼리 매개변수를 참고하세요.

요청 본문에 다음을 포함해야 합니다.

client_id: 클라이언트의 고유 식별자입니다. Firebase app_instance_id와는 다릅니다. gtag.js('get')를 사용하세요.

user_id: 선택사항입니다. 사용자의 고유 식별자입니다. UTF-8 문자만 포함할 수 있습니다. 이 식별자에 관한 자세한 내용은 교차 플랫폼 분석용 User-ID를 참고하세요.
consent: 선택사항. 동의 설정을 설정하는 방법을 알아보세요.
timestamp_micros: 선택사항. 요청의 이벤트 및 사용자 속성에 대한 유닉스 시간(마이크로초)입니다. 지정되지 않은 경우 기본값은 요청 시간입니다.
events: 이벤트 항목의 배열입니다. 하나의 요청에 여러 이벤트를 포함할 수 있습니다.

실시간 보고서와 같은 보고서에 사용자 활동을 표시하려면 event에 대한 params의 일부로 engagement_time_msec 및 session_id가 제공되어야 합니다. engagement_time_msec 매개변수는 이벤트의 참여 시간을 밀리초로 반영해야 합니다.

예를 들면 다음과 같습니다.

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

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

직접 해 보기

다음은 여러 이벤트를 한 번에 전송하는 데 사용할 수 있는 예입니다. 이 예에서는 tutorial_begin 이벤트와 join_group 이벤트를 Google 애널리틱스 서버로 전송합니다.

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "engagement_time_msec": 150
        }
      }
    ]
  })
});

타임스탬프 재정의

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

이벤트의 timestamp_micros입니다.
요청의 timestamp_micros로,
측정 프로토콜이 요청을 수신한 시간입니다.

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

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

다음 예에서는 요청 수준 타임스탬프와 이벤트 수준 타임스탬프를 모두 전송합니다. 따라서 측정 프로토콜은 tutorial_begin 이벤트에 tutorialBeginUnixEpochTimeInMicros 타임스탬프를, join_group 이벤트에 requestUnixEpochTimeInMicros 타임스탬프를 할당합니다.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

제한사항

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

요청은 최대 25개의 이벤트를 포함할 수 있습니다.
이벤트는 최대 25개의 매개변수를 포함할 수 있습니다.
이벤트는 최대 25개의 사용자 속성을 포함할 수 있습니다.
사용자 속성 이름은 24자(영문 기준) 이하여야 합니다.
사용자 속성 값은 36자(영문 기준) 이하여야 합니다.
이벤트 이름은 40자(영문 기준) 이하여야 하고 영숫자 및 밑줄 문자만 사용할 수 있으며 알파벳으로 시작해야 합니다.
항목 매개변수를 포함한 매개변수 이름은 40자(영문 기준) 이하여야 하고 영숫자 및 밑줄 문자만 사용할 수 있으며 알파벳으로 시작해야 합니다.
상품 매개변수 값을 포함한 매개변수 값은 표준 Google 애널리틱스 속성의 경우 100자(영문 기준) 이하여야 하며 Google 애널리틱스 360 속성의 경우 500자(영문 기준) 이하여야 합니다.
항목 매개변수는 최대 10개의 맞춤 매개변수를 포함할 수 있습니다.
POST 본문은 130KB보다 작아야 합니다.
Google 애널리틱스로 전송된 앱 측정 프로토콜 이벤트는 앱 사용자를 위한 Google Ads의 검색 잠재고객을 채우지 않습니다.

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