Referencia del Protocolo de medición

En este documento se describe cómo enviar datos a Google Analytics mediante el Protocolo de medición.

Descripción general

El envío de datos a Google Analytics mediante el Protocolo de medición se divide en dos partes:

  • El transporte: dónde y cómo se envían los datos.
  • La carga: los datos que se envían.

En este documento se describe cómo dar formato a ambas partes.

Transporte

Extremo de la URL

Para enviar datos mediante el Protocolo de medición, envía solicitudes HTTP al extremo siguiente:

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

Todos los datos deben enviarse de forma segura con el protocolo HTTPS.

Puedes enviar datos mediante solicitudes POST o GET.

Con POST

Te recomendamos que envíes datos a través de POST porque permite una carga mayor. Si te decantas por POST, emite la siguiente solicitud HTTP:

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

Donde:

  • user_agent_string: es una cadena de agente de usuario con formato que se usa para calcular las dimensiones siguientes: navegador, plataforma y funciones para dispositivos móviles.

    Si este valor no está configurado, no se calcularán los datos anteriores.

  • payload_data: atributo BODY de la solicitud POST. El cuerpo debe incluir justo una carga codificada de URI y no puede superar los 8.192 bytes.
  • IP Address – Is implicitly sent in the HTTP request and is used to compute all the geo / network dimensions in Google Analytics.

GET

En los entornos en los que no se pueden enviar datos POST, también puedes enviar solicitudes HTTP GET al mismo extremo:

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

Donde los datos de carga útil se envían como parámetros de consulta de URI con escape. La longitud de la URL codificada no puede superar los 8000 bytes.

Prevenir el almacenamiento en memoria caché

En algunos entornos, por ejemplo, los navegadores, puede que las solicitudes HTTP GET se almacenen en la memoria caché. Cuando esto sucede, puede que las solicitudes posteriores se recuperen de la memoria caché y no se envíen a Google Analytics. Para impedir que se active el almacenamiento en memoria caché, el protocolo de medición proporciona un parámetro especial (z) que se puede establecer con un número aleatorio. Esto garantiza que todas las solicitudes del protocolo de medición sean únicas y que las solicitudes posteriores no se recuperen de la memoria caché.

Si utilizas la prevención de almacenamiento en memoria caché, te recomendamos que agregues el parámetro correspondiente como el último de la carga.

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

Códigos de respuesta

El protocolo de medición devuelve un código de estado 2xx si se recibe la solicitud HTTP. Pero no devuelve un código de error si los datos de carga tienen un formato incorrecto o si los datos de la carga son incorrectos o Google Analytics no los procesa.

Si no recibes un código de estado 2xx, NO tienes que reintentar la solicitud, sino detener la solicitud HTTP y corregir cualquier error.

Datos de la carga

Todos los datos que Google Analytics recopila mediante el protocolo de medición se envían como carga. La carga tiene el mismo formato que una cadena de consulta URL donde cada parámetro tiene una clave y un valor, está separado por un carácter = y cada par está delimitado con un carácter &. Por ejemplo:

key1=val1&key2=val2

Cada carga tiene reglas que la rigen: los valores necesarios, la codificación del URI, los parámetros que se pueden enviar juntos y la longitud del parámetro. Además, cada parámetro tiene un tipo específico que exige un formato concreto. En las siguientes secciones se analizan estas reglas.

Consulta la referencia de parámetros para obtener una lista completa de todos los parámetros que puedes enviar mediante el protocolo de medición.

Valores necesarios para todos los hits

Los siguientes parámetros deben estar presentes en cada carga:

Nombre Parámetro Ejemplo Descripción
Versión del protocolo v v=1 La versión del protocolo. El valor debe ser 1.
ID de seguimiento tid tid=UA-123456-1 El ID que señala la propiedad de Google Analytics a la que hay que enviar los datos.
ID de cliente cid cid=xxxxx Un ID único para un usuario en particular.
Tipo de hit t t=pageview El tipo de interacción recopilada para un usuario concreto.

Los datos de ID de cliente y tipo de hit son los valores que se asignan directamente al modelo de datos de Google Analytics. Si quieres hacer un seguimiento del usuario 5555 que ha entrado en /pageA, en /pageB y en /pageC, tienes que enviar las tres cargas siguientes:

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

Ten en cuenta que el carácter / se ha codificado como %2F.

Valores de codificación de URLs

Todos los valores que se envían a Google Analytics deben estar codificados para URL y para UTF-8. Para enviar la clave dp con el valor /my page €, primero tienes que asegurarte de que esté codificado para UTF-8 y después para URL. El resultado es la cadena final:

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

Si alguno de los caracteres está mal codificado, se cambia por el carácter Unicode de sustitución xFFFD.

Valores necesarios para ciertos tipos de hit

Algunos parámetros solo se pueden enviar con tipos de hit específicos. Por ejemplo, para el tipo de hit pageview es necesario que el parámetro de ruta de página (dp) también esté establecido. En la referencia de parámetros se describen los parámetros necesarios para cada tipo de hit.

Longitud máxima

Algunos de los valores de texto del protocolo de medición tienen longitudes de bytes máximas específicas. Por ejemplo, el campo del documento de referencia dr tiene una longitud máxima de 2048 Bytes. Si alguno de los valores supera la longitud máxima, se trunca automáticamente. Si un carácter multibyte supera la longitud máxima, se trunca todo el carácter.

Tipos de datos admitidos

Cada campo de datos del protocolo de medición pertenece a un tipo específico con sus propias reglas de validación. Si alguno de los valores del parámetro no cumple las reglas de validación, Google Analytics ignora el parámetro en cuestión y no lo procesa. El resto de parámetros se procesa con normalidad.

El protocolo de medición admite los siguientes tipos de datos:

Ten en cuenta que cada campo de datos concreto puede tener sus propias restricciones. Consulta la referencia de campos para obtener una lista completa de todos los campos de datos y de los tipos aceptados.

Texto

Se utiliza para representar cadenas. En los campos de texto se lleva a cabo procesamiento adicional. Se eliminan todos los espacios en blanco iniciales y finales. El funcionamiento interno de dos o más caracteres de espacio en blanco (incluidos el espacio, el tabulador, los saltos de línea, etc.) se reduce a un solo carácter de espacio. Esta transformación se aplica al texto sin procesar antes de que se produzca un truncamiento. Por ejemplo:

   Hello      World

Se convierte en:

Hello World

Moneda

Se utiliza para representar el valor total de una moneda. Se utiliza un punto decimal como delimitador entre la parte entera y la parte fraccionaria de la moneda. La precisión es de seis decimales como máximo. El siguiente valor es válido para un campo de moneda:

1000.000001

Cuando el valor se envía a Google Analytics, se elimina todo el texto hasta el primer dígito, el carácter - o el carácter . (decimal). Por lo tanto:

$-55.00

Se convierte en:

-55.00

Booleano

Se utiliza para determinar si un valor es verdadero o falso. Los valores válidos son:

  • 1: verdadero,
  • 0: falso.

Entero

Se utiliza para representar un número entero. El valor se guarda como un entero int64 con signo.

Número

Se utiliza para representar un número entero o un número de punto flotante.