이 문서에서는 측정 프로토콜을 사용하여 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의 길이는 8000바이트 이하여야 합니다.
캐시 무효화
브라우저와 같은 일부 환경에서는 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로 저장됩니다.
숫자
정수 또는 부동 소수점 숫자를 나타내는 데 사용됩니다.