Cómo usar la API de CrUX

Aprende a usar la API de Chrome UX Report para obtener acceso a datos de la experiencia del usuario real en millones de sitios web.

Rick Viscomi

Shane Exterkamp

El conjunto de datos del Chrome UX Report (CrUX) representa cómo los usuarios de Chrome del mundo real experimentan destinos populares en la Web. Desde 2017, cuando se lanzó por primera vez el conjunto de datos consultable en BigQuery, los datos de campo de CrUX se integraron en herramientas para desarrolladores, como PageSpeed Insights, el Panel de CrUX y el informe de Métricas web esenciales de Search Console, lo que permite a los desarrolladores medir y supervisar las experiencias de los usuarios reales. La parte que falta todo este tiempo es una herramienta que proporciona acceso gratuito y RESTful a los datos de CrUX de manera programática. Para ayudar a cerrar esa brecha, nos complace anunciar el lanzamiento de la nueva API de Chrome UX Report.

Esta API se creó con el objetivo de proporcionar a los desarrolladores un acceso simple, rápido y completo a los datos de CrUX. La API de CrUX solo informa datos de la experiencia del usuario en el campo, a diferencia de la API de PageSpeed Insights existente, que también incluye datos de lab de las auditorías de rendimiento de Lighthouse. La API de CrUX está optimizada y puede entregar datos de la experiencia del usuario con rapidez, por lo que es ideal para aplicaciones de auditoría en tiempo real.

Para garantizar que los desarrolladores tengan acceso a todas las métricas más importantes (las Métricas web esenciales), la API de CrUX audita y supervisa Largest Contentful Paint (LCP), Interaction to Next Paint (INP) y Cumulative Layout Shift (CLS) tanto a nivel del origen como de la URL.

¡Así que comencemos y veamos cómo usarlo!

Datos de origen de consulta

Los orígenes en el conjunto de datos de CrUX abarcan todas las experiencias subyacentes a nivel de página. En el siguiente ejemplo, se muestra cómo consultar a la API de CrUX los datos de la experiencia del usuario de un origen usando cURL en la línea de comandos.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"origin": "https://web.dev"}'

Nota: Todas las solicitudes a la API deben proporcionar un valor para el parámetro key. En el ejemplo anterior, [YOUR_API_KEY] se deja como marcador de posición. Obtén tu propia clave privada de API de CrUX como se describe en la documentación de la API de CrUX.

El comando curl consta de tres partes:

1. El extremo de URL de la API, incluida la clave de API privada del emisor.
2. El encabezado Content-Type: application/json, que indica que el cuerpo de la solicitud contiene JSON.
3. El cuerpo de la solicitud codificado en JSON, que especifica el origen https://web.dev

Para hacer lo mismo en JavaScript, usa la utilidad CrUXApiUtil. que realiza la llamada a la API y muestra la respuesta decodificada (consulta también nuestra variante de GitHub). para acceder a más funciones, como el historial y la asistencia por lotes).

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

Reemplaza [YOUR_API_KEY] por tu clave. A continuación, llama a la función CrUXApiUtil.query y pasa el objeto cuerpo de la solicitud.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Si existen datos para este origen, la respuesta de la API es un objeto codificado en JSON que contiene métricas que representan la distribución de las experiencias del usuario. Las métricas de distribución son los percentiles y discretizaciones de histogramas.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            "density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

Las propiedades start y end del objeto histogram representan el rango de valores que experimentan los usuarios para la métrica determinada. La propiedad density representa la proporción de experiencias del usuario dentro de ese rango. En este ejemplo, el 79% de las experiencias del usuario de LCP en todas las páginas web.dev duran menos de 2,500 milisegundos, que es lo “bueno”. Umbral de LCP. El valor percentiles.p75 significa que el 75% de las experiencias del usuario en esta distribución duran menos de 2,216 milisegundos. Obtén más información sobre la estructura de respuesta en la documentación del cuerpo de la respuesta.

Errores

Cuando la API de CrUX no tiene ningún dato para un origen determinado, responde con un mensaje de error codificado en JSON:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

Para depurar este error, primero verifica que el origen solicitado se pueda navegar de forma pública. Para probar esto, ingresa el origen en la barra de direcciones de tu navegador y compáralo con la URL final después de cualquier redireccionamiento. Entre los problemas habituales, se incluyen agregar o omitir el subdominio innecesariamente y usar el protocolo HTTP incorrecto.

Error

{"origin": "http://www.web.dev"}

Este origen incluye de forma incorrecta el protocolo http:// y el subdominio www..

Listo

{"origin": "https://web.dev"}

Este origen es navegable de forma pública.

Si el origen solicitado es la versión navegable, este error también puede ocurrir si el origen no tiene una cantidad suficiente de muestras. Todos los orígenes y las URLs incluidos en el conjunto de datos deben tener una cantidad suficiente de muestras para anonimizar usuarios individuales. Además, las URLs y los orígenes deben ser indexables públicamente. Consulta la metodología de CrUX para obtener más información sobre cómo se incluyen los sitios web en el conjunto de datos.

Datos de URL de consulta

Viste cómo consultar a la API de CrUX la experiencia general del usuario en un origen. Para restringir los resultados a una página en particular, usa el parámetro de solicitud url.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

Este comando cURL es similar al ejemplo de origen, excepto que el cuerpo de la solicitud usa el parámetro url para especificar la página que se debe buscar.

Para consultar datos de URL desde la API de CrUX en JavaScript, llama a la función CrUXApiUtil.query con el parámetro url en el cuerpo de la solicitud.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Si existen datos para esta URL en el conjunto de datos de CrUX, la API mostrará una respuesta codificada en JSON. Por ejemplo:

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

Verdadero para formar, los resultados muestran que https://web.dev/fast/ tiene un 85% de "bueno". Experiencias de LCP y un percentil 75 de 1,947 milisegundos, que es apenas mejor que la distribución en todo el origen.

Normalización de URL

La API de CrUX puede normalizar las URLs solicitadas para que coincidan mejor con la lista de URLs conocidas. Por ejemplo, consultar la URL https://web.dev/fast/#measure-performance-in-the-field generará datos de https://web.dev/fast/ debido a la normalización. Cuando esto suceda, se incluirá un objeto urlNormalizationDetails en la respuesta.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

Obtén más información sobre la normalización de URLs en la documentación de CrUX.

Realiza consultas por factor de forma

Término clave: Un factor de forma es el tipo de dispositivo en el que un usuario visita un sitio web. Entre los tipos de dispositivos comunes, se incluyen las computadoras de escritorio, los teléfonos y las tablets.

Las experiencias de los usuarios pueden variar significativamente en función de las optimizaciones del sitio web, dispositivos. Para comprender mejor estas diferencias, desglosa el origen y el rendimiento de las URLs con la dimensión formFactor de la API de CrUX.

La API admite tres valores explícitos de factores de forma: DESKTOP, PHONE y TABLET. Además del origen o la URL, especifica uno de estos valores en el cuerpo de la solicitud para restringir los resultados solo a esas experiencias del usuario. En este ejemplo, se muestra cómo consultar la API por factor de forma con cURL.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

Para consultar datos específicos de factores de forma en la API de CrUX mediante JavaScript, llama a la función CrUXApiUtil.query con los parámetros url y formFactor del cuerpo de la solicitud.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Omitir el parámetro formFactor equivale a solicitar datos para todos los factores de forma combinados.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

El campo key de la respuesta repetirá la configuración de solicitud formFactor para confirmar que solo se incluyen las experiencias del teléfono.

Precaución: Cuanto más detallada sea la solicitud (por ejemplo, una combinación específica de URL y factor de forma), menos experiencias del usuario incluirá. Esto puede provocar que la detección de "no encontradas" sea más frecuente en especial cuando se consultan URLs menos populares o el tipo de tablet menos popular.

Recuerda de la sección anterior que el 85% de las experiencias del usuario en esta página fueron "buenas" y un LCP. Compara eso con las experiencias específicas del teléfono, de las cuales solo el 78% se consideran “buenas”. El percentil 75 también es más lento entre las experiencias del teléfono, en un rango de 1,947 a 2,366 milisegundos. La segmentación por factor de forma tiene el potencial de resaltar disparidades más extremas en las experiencias del usuario.

Evalúa el rendimiento de las Métricas web esenciales

El programa Métricas web esenciales define objetivos que ayudan a determinar si una experiencia del usuario o una distribución de experiencias pueden considerarse "buenas". En el siguiente ejemplo, usamos la API de CrUX y la función CrUXApiUtil.query para evaluar si la distribución de las métricas de Métricas web esenciales (LCP, INP, CLS) de una página web es “buena”.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the "good" threshold.
    const passes = p75 < threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

Punto clave: Solo se puede llamar a la API con un origen o una URL a la vez. Para evaluar varios sitios web o páginas, realiza llamadas independientes a la API.

Los resultados muestran que esta página pasa las evaluaciones de Core Web Vitals de las tres métricas.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

Si se combinan con una forma automatizada de supervisar los resultados de la API, los datos de CrUX se pueden usar para garantizar que las experiencias de los usuarios reales sean rápidas y se mantengan así. Para obtener más información sobre las Métricas web esenciales y cómo medirlas, consulta Métricas web y Herramientas para medir las Métricas web esenciales.

Próximos pasos

Las funciones incluidas en la versión inicial de la API de CrUX solo ayudan a explorar la superficie de los tipos de estadísticas que son posibles con CrUX. Es posible que los usuarios del conjunto de datos de CrUX en BigQuery estén familiarizados con algunas de las funciones más avanzadas, incluidas las siguientes:

• Métricas adicionales
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• Dimensiones adicionales
  • month
  • country
  • effective connection type (ECT)
• Nivel de detalle adicional
  • histogramas detallados
  • percentiles más

Consulta los documentos de la API de CrUX oficiales para adquirir tu clave de API y explorar más aplicaciones de ejemplo. Esperamos que lo pruebes y nos encantaría recibir tus preguntas o comentarios. Comunícate con nosotros en el foro de discusión de CrUX. Para estar al tanto de todo lo que planeamos para la API de CrUX, suscríbete al foro de anuncios de CrUX o síguenos en Twitter en @ChromeUXReport.