Referencia del Protocolo de medición

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

Descripción general

Existen 2 partes para enviar datos a Google Analytics a través del Protocolo de medición:

  • El transporte: hasta dónde y cómo envías los datos
  • La carga útil, es decir, los datos que envías

En este documento, se describe cómo dar formato a ambos.

Transporte

Extremo de URL

Para enviar datos con el Protocolo de medición, debes realizar solicitudes HTTP al siguiente extremo:

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.

Cómo usar POST

Recomendamos enviar los datos a través de POST porque permite una carga útil más grande. Cuando uses POST, emite la siguiente solicitud HTTP:

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

Aquí:

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

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

  • payload_data: el BODY de la solicitud de publicación El cuerpo debe incluir exactamente 1 carga útil codificada en URI y no debe tener más de 8,192 bytes.
  • Dirección IP: se envía de forma implícita en la solicitud HTTP y se usa para calcular todas las dimensiones de ubicación geográfica y red en Google Analytics.

GET

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

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

Dónde se envían los datos de carga útil como parámetros de consulta con escape de URI. La longitud de toda la URL codificada no debe superar los 8,000 bytes.

Eliminación de caché

En algunos entornos, como los navegadores, las solicitudes GET de HTTP pueden almacenarse en caché. Cuando una solicitud se almacena en caché, es posible que se recuperen las solicitudes posteriores de esta y no se envíen a Google Analytics. Para analizar la 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 caché.

Cuando usas el bloqueador de caché, te recomendamos que agregues este parámetro como último parámetro en la carga útil.

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

Códigos de respuesta

El Protocolo de medición mostrará un código de estado 2xx si se recibió la solicitud HTTP. El Protocolo de medición no muestra un código de error si los datos de la carga útil tienen errores de formato, o si los datos en la carga útil eran incorrectos o Google Analytics no los procesó.

Si no obtienes un código de estado 2xx, NO debes reintentar la solicitud. En cambio, debes detenerte y corregir cualquier error en tu solicitud HTTP.

Datos de carga útil

Todos los datos que recopila Google Analytics con el Protocolo de medición se envían como una carga útil. La carga útil se asemeja a una cadena de consulta de URL en la que cada parámetro tiene una clave y un valor, está separado por un carácter = y cada par está delimitado por un carácter &. Por ejemplo:

key1=val1&key2=val2

Cada carga útil tiene reglas que rigen: valores obligatorios, codificación de URI, parámetros que se pueden enviar juntos y longitud de parámetros. Además, cada parámetro tiene un tipo específico que requiere un formato en particular. En las siguientes secciones, se explican estas reglas.

Consulta la Referencia de parámetros para obtener una lista completa de todos los parámetros que puedes enviar con el Protocolo de medición.

Valores obligatorios para todos los hits

Los siguientes parámetros deben estar en cada carga útil:

Nombre Parámetro Ejemplo Descripción
Versión del protocolo v v=1 Indica la versión del protocolo. El valor debe ser 1.
ID de seguimiento tid tid=UA-123456-1 Es el ID que distingue a qué propiedad de Google Analytics se envían 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 en particular.

Los datos de Client ID y Hit Type son valores que se asignan directamente al modelo de datos de Google Analytics. Si quisieras hacer un seguimiento del usuario 5555 que visitó /pageA, /pageB y /pageC, enviarías las siguientes 3 cargas útiles:

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

Observa que la / se codificó como %2F.

Valores de codificación de URL

Todos los valores que se envían a Google Analytics deben estar en formato UTF-8 y estar codificados para URLs. Para enviar la clave dp con el valor /my page €, primero debes asegurarte de que esté codificada en UTF-8 y, luego, en la URL, lo que da como resultado la string final:

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

Si alguno de los caracteres está codificado de forma incorrecta, se reemplazará por el carácter de reemplazo de Unicode xFFFD.

Valores obligatorios para ciertos tipos de hits

Es posible que algunos parámetros solo se envíen con tipos de hits específicos. Por ejemplo, el tipo de hit pageview requiere que también se configure el parámetro de ruta de la página (dp). En la Referencia de parámetros, se describe qué parámetros son obligatorios para cada tipo de hit.

Longitud máxima

Algunos valores de texto en el Protocolo de medición tienen longitudes máximas específicas en bytes. Por ejemplo, el campo dr de referencia del documento tiene una longitud máxima de 2,048 bytes. Si alguno de los valores supera las longitudes máximas, se truncará automáticamente. Si un carácter de varios bytes excede la longitud máxima, se truncará todo el carácter.

Tipos de datos admitidos

Cada campo de datos en el Protocolo de medición pertenece a un tipo específico, cada uno con sus propias reglas de validación. Si alguno de los valores del parámetro no cumple con las reglas de validación, se ignorará el parámetro específico y Google Analytics no lo procesará. Todos los demás parámetros se procesarán de la manera habitual.

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

Ten en cuenta que los campos de datos individuales pueden tener sus propias restricciones. Consulta la Referencia de campos para obtener una lista completa de todos los campos de datos y los tipos aceptados.

Texto

Se usa para representar cadenas. Se realiza un procesamiento adicional en los campos de texto. Se quitan todos los caracteres de espacio en blanco iniciales y finales. Las ejecuciones internas de dos o más caracteres de espacio en blanco (incluidos el espacio, la tabulación, las líneas nuevas, etc.) se reducen a un solo carácter de espacio. Esta transformación se aplica al texto sin procesar antes de cualquier truncamiento. Por ejemplo:

   Hello      World

se convertirá en:

Hello World

Moneda

Se usa para representar el valor total de una moneda. Se usa un punto decimal como delimitador entre la parte entera y la fraccionaria de la moneda. La precisión es de hasta 6 decimales. Lo siguiente es válido para un campo de moneda:

1000.000001

Una vez que se envía el valor a Google Analytics, se quita todo el texto hasta el primer dígito, el carácter - o el carácter . (decimal). Entonces:

$-55.00

se convertirá en:

-55.00

Booleano

Se usa para determinar si un valor es verdadero o falso. Estos son los valores válidos:

  • 1: Verdadero
  • 0: Falso

Número entero

Se usa para representar un número entero. El valor se almacena como un valor int64 firmado

Número

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