이 문서에서는 측정 프로토콜을 사용하여 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 애널리틱스에서 모든 지역 및 네트워크 측정기준을 계산하는 데 사용됩니다.
GET
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 인코딩이어야 합니다.
dp 키를 /my page € 값과 함께 전송하려면 먼저 UTF-8로 인코딩된 후 URL로 인코딩하여 최종 문자열이 되도록 해야 합니다.
dp=%2Fmy%20page%20%E2%82%AC
잘못 인코딩된 문자가 있으면 유니코드 대체 문자 xFFFD로 대체됩니다.
특정 조회 유형의 필수 값
일부 매개변수는 특정 조회 유형으로만 전송될 수 있습니다.
예를 들어 pageview 조회 유형을 사용하려면 페이지 경로 매개변수 (dp)도 설정해야 합니다. 매개변수 참조에서는 조회 유형에 어떤 매개변수가 필요한지 설명합니다.
최대 길이
측정 프로토콜의 일부 텍스트 값에는 바이트 단위의 특정 최대 길이가
지정되어 있습니다. 예를 들어 문서 리퍼러 필드 dr의 최대 길이는 2,048바이트입니다. 값이 최대 길이보다 크면 자동으로 잘립니다. 멀티바이트 문자가 최대 길이를 초과하면 전체 문자가 잘립니다.
지원되는 데이터 유형
측정 프로토콜의 각 데이터 필드는 특정 유형에 속하며, 각각 자체 유효성 검사 규칙이 있습니다. 매개변수 값이 유효성 검사 규칙을 준수하지 않는 경우 해당 매개변수는 무시되고 Google 애널리틱스에서 처리되지 않습니다. 다른 모든 매개변수는 정상적으로 처리됩니다.
측정 프로토콜은 다음과 같은 데이터 유형을 지원합니다.
개별 데이터 필드에는 자체 제한사항이 있을 수 있습니다. 모든 데이터 필드와 허용되는 유형의 전체 목록은 필드 참조를 확인하세요.
텍스트
문자열을 나타내는 데 사용됩니다. 텍스트 필드에서 추가 처리가 이루어집니다. 모든 선행 및 후행 공백 문자가 제거됩니다. 두 개 이상의 공백 문자 (공백, 탭, 줄바꿈 등)의 내부 실행이 단일 공백 문자로 줄어듭니다. 이 변환은 잘림이 발생하기 전에 원시 텍스트에 적용됩니다. 예를 들면 다음과 같습니다.
Hello World
다음과 같이 변환됩니다.
Hello World
통화
통화의 총 가치를 나타내는 데 사용됩니다. 소수점은 통화의 전체 부분과 소수 부분 사이에 구분 기호로 사용됩니다. 정확도는 소수점 아래 6자리까지입니다. 통화 필드에 유효한 사항은 다음과 같습니다.
1000.000001
값이 Google 애널리틱스로 전송되면
첫 번째 자리인 - 문자 또는 .(소수점) 문자에 앞의 모든 텍스트가
삭제됩니다. 따라서
$-55.00
다음과 같이 변환됩니다.
-55.00
불리언
값이 참인지 거짓인지 판단하는 데 사용됩니다. 유효한 값은 다음과 같습니다.
1~참0– 거짓
정수
정수를 나타내는 데 사용됩니다. 값은 부호 있는 int64로 저장됩니다.
숫자
정수 또는 부동 소수점 숫자를 나타내는 데 사용됩니다.