측정 프로토콜 참조

이 문서에서는 측정 프로토콜을 사용하여 Google 애널리틱스로 데이터를 전송하는 방법을 설명합니다.

개요

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

  • 전송 – 데이터를 전송하는 위치 및 방법
  • 페이로드 – 전송하는 데이터

이 문서에서는 두 가지 모두 형식을 지정하는 방법을 설명합니다.

전송

URL 엔드포인트

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

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

모든 데이터는 HTTPS 프로토콜을 사용하여 안전하게 전송되어야 합니다.

POST 또는 GET 요청을 사용하여 데이터를 보낼 수 있습니다.

POST 사용

페이로드가 더 크기 때문에 POST를 통해 데이터를 전송하는 것이 좋습니다. POST를 사용하는 경우 다음 HTTP 요청을 실행합니다.

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

각 항목의 의미는 다음과 같습니다.

  • user_agent_string – 브라우저, 플랫폼, 모바일 기능과 같은 측정기준을 계산하는 데 사용되는 형식의 사용자 에이전트 문자열입니다.

    이 값을 설정하지 않으면 위의 데이터는 계산되지 않습니다.

  • payload_data – 게시 요청의 BODY입니다. 본문에는 URI로 인코딩된 페이로드가 정확히 1개 있어야 하며 8,192바이트 이하여야 합니다.
  • IP 주소 – HTTP 요청에서 암시적으로 전송되며 Google 애널리틱스의 모든 지역/네트워크 측정기준을 계산하는 데 사용됩니다.

YouTube 최신 소식 확인하기

POST 데이터를 보낼 수 없는 환경의 경우 동일한 엔드포인트로 HTTP GET 요청을 보낼 수도 있습니다.

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

페이로드 데이터가 URI 이스케이프된 쿼리 매개변수로 전송되는 위치입니다. 인코딩된 URL의 전체 길이는 8,000바이트 이하여야 합니다.

캐시 무효화

브라우저와 같은 일부 환경에서는 HTTP GET 요청이 캐시될 수 있습니다. 요청이 캐시되면 후속 요청이 캐시에서 검색되어 Google 애널리틱스로 전송되지 않을 수 있습니다. 캐시를 우회하기 위해 측정 프로토콜은 랜덤 숫자로 설정할 수 있는 특수 매개변수(z)를 제공합니다. 이렇게 하면 모든 측정 프로토콜 요청이 고유하며 후속 요청은 캐시에서 검색되지 않습니다.

캐시 버스터를 사용할 때는 페이로드에 이 매개변수를 마지막 매개변수로 추가하는 것이 좋습니다.

https://www.google-analytics.com/collect?payload_data&z=123456

응답 코드

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

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

페이로드 데이터

측정 프로토콜을 사용하여 Google 애널리틱스에서 수집하는 모든 데이터는 페이로드로 전송됩니다. 페이로드는 각 매개변수에 키 및 값이 있고, = 문자로 구분되며, 각 쌍이 & 문자로 구분되는 URL 쿼리 문자열과 유사합니다. 예를 들면 다음과 같습니다.

key1=val1&key2=val2

각 페이로드에는 필수 값, URI 인코딩, 함께 전송할 수 있는 매개변수, 매개변수 길이에 적용되는 규칙이 있습니다. 또한 각 매개변수에는 특정 형식을 요구하는 특정 유형이 있습니다. 다음 섹션에서는 이러한 규칙을 설명합니다.

매개변수 참조에서 측정 프로토콜을 사용하여 전송할 수 있는 모든 매개변수의 전체 목록을 확인하세요.

모든 조회수의 필수 값

각 페이로드에는 다음 매개변수가 있어야 합니다.

이름 매개변수 예 설명
프로토콜 버전 v v=1 프로토콜 버전입니다. 값은 1여야 합니다.
추적 ID tid tid=UA-123456-1 데이터를 전송할 Google 애널리틱스 속성을 구분하는 ID입니다.
클라이언트 ID cid cid=xxxxx 특정 사용자의 고유한 ID입니다.
조회 유형 t t=pageview 특정 사용자에 대해 수집되는 상호작용 유형입니다.

Client ID 및 Hit Type 데이터는 Google 애널리틱스 데이터 모델에 직접 매핑되는 값입니다. /pageA, /pageB, /pageC으로 이동한 사용자 5555를 추적하려면 다음 3개의 페이로드를 전송합니다.

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

/는 %2F로 인코딩되었습니다.

URL 인코딩 값

Google 애널리틱스로 전송되는 모든 값은 UTF-8 및 URL 인코딩이어야 합니다. 값이 /my page €인 키 dp를 전송하려면 먼저 UTF-8로 인코딩된 후 URL로 인코딩되어야 합니다. 그러면 최종 문자열이 생성됩니다.

dp=%2Fmy%20page%20%E2%82%AC

잘못 인코딩된 문자가 있으면 유니코드 대체 문자(xFFFD)로 대체됩니다.

특정 조회 유형의 필수 값

일부 매개변수는 특정 조회 유형과만 함께 전송될 수 있습니다. 예를 들어 pageview 조회 유형을 사용하려면 Page Path 매개변수(dp)도 설정해야 합니다. 매개변수 참조에서는 조회 유형에 필요한 매개변수를 설명합니다.

최대 길이

측정 프로토콜의 일부 텍스트 값은 특정 최대 길이(바이트)를 갖습니다. 예를 들어 문서 리퍼러 필드 dr의 최대 길이는 2,048바이트입니다. 값이 최대 길이보다 크면 자동으로 잘립니다. 멀티바이트 문자가 최대 길이를 초과하면 문자 전체가 잘립니다.

지원되는 데이터 유형

측정 프로토콜의 각 데이터 필드는 특정 유형에 속하며, 각 유형에는 자체 검증 규칙이 있습니다. 매개변수 값 중 하나라도 검증 규칙을 준수하지 않으면 해당 매개변수는 무시되며 Google 애널리틱스에서 처리되지 않습니다. 다른 모든 매개변수는 평소와 같이 처리됩니다.

측정 프로토콜은 다음 데이터 유형을 지원합니다.

개별 데이터 필드에는 자체 제한사항이 있을 수 있습니다. 모든 데이터 필드와 허용되는 유형의 전체 목록은 필드 참조를 확인하세요.

텍스트

문자열을 나타내는 데 사용됩니다. 텍스트 필드에 대한 추가 처리가 수행됩니다. 모든 선행 및 후행 공백 문자가 삭제됩니다. 두 개 이상의 공백 문자 (공백, 탭, 줄바꿈 등)의 내부 실행이 단일 공백 문자로 축소됩니다. 이 변환은 잘림 전에 원시 텍스트에 적용됩니다. 예를 들면 다음과 같습니다.

   Hello      World

다음과 같이 변환됩니다.

Hello World

통화

통화의 총 가치를 나타내는 데 사용됩니다. 소수점은 통화의 전체 부분과 소수 부분 사이의 구분 기호로 사용됩니다. 정확도는 소수점 아래 6자리까지입니다. 다음은 통화 필드에 유효한 설명입니다.

1000.000001

값이 Google 애널리틱스로 전송되면 첫 번째 자리인 - 문자 또는 .(소수점) 문자에 앞의 모든 텍스트가 삭제됩니다. 따라서

$-55.00

다음과 같이 변환됩니다.

-55.00

불리언

값이 참인지 거짓인지 판단하는 데 사용됩니다. 유효한 값은 다음과 같습니다.

  • 1~참
  • 0~거짓

정수

정수를 나타내는 데 사용됩니다. 값은 서명된 int64로 저장됩니다.

숫자

정수 또는 부동 소수점 숫자를 나타내는 데 사용됩니다.