Cómo usar la API de CrUX

Aprende a utilizar la API de Chrome UX Report para acceder a datos sobre la experiencia del usuario real en millones de sitios web.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

El conjunto de datos del Informe de UX de Chrome (CrUX) representa cómo los usuarios de Chrome del mundo real experimentan los destinos populares de 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 Métricas web esenciales de Search Console, lo que les permite a los desarrolladores medir y supervisar las experiencias de usuarios reales. La pieza que nos 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 compiló 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 sobre la experiencia del usuario en un campo, a diferencia de la API de PageSpeed Insights existente, que también informa datos de lab de las auditorías de rendimiento de Lighthouse. La API de CrUX está optimizada y puede entregar datos sobre 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 el Procesamiento de imagen con contenido más grande (LCP), el Retraso de primera entrada (FID) y el Cambio de diseño acumulado (CLS) a nivel del origen y de la URL.

Así que profundicemos y veamos cómo usarlo.

Datos de origen de la consulta

Los orígenes en el conjunto de datos de CrUX abarcan todas las experiencias subyacentes a nivel de la página. En el siguiente ejemplo, se muestra cómo consultar la API de CrUX para obtener datos de la experiencia del usuario de un origen con 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"}'

El comando curl consta de tres partes:

  1. El extremo de URL de la API, incluida la clave de API privada del llamador
  2. El encabezado Content-Type: application/json, que indica que el cuerpo de la solicitud contiene JSON.
  3. El cuerpo de la solicitud con codificación 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 ver más funciones, como la compatibilidad con el historial y los 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 del 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 metrics que representan la distribución de las experiencias de los usuarios. Las métricas de distribución son contenedores de histogramas y percentiles.

{
  "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 de 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 el umbral de LCP “bueno”. El valor percentiles.p75 significa que el 75% de las experiencias de los usuarios en esta distribución duran menos de 2,216 milisegundos. Obtén más información sobre la estructura de la respuesta en la documentación del cuerpo de la respuesta.

Errores

Cuando la API de CrUX no tiene datos de 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 del navegador y compáralo con la URL final después de los redireccionamientos. Los problemas comunes incluyen omitir o agregar innecesariamente el subdominio 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..

Se completó correctamente
{"origin": "https://web.dev"}

Este origen es navegable públicamente.

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 a los usuarios individuales. Además, los orígenes y las URLs deben poder indexarse 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 la API de CrUX para obtener 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 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 los datos de esta URL existen 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
        }
      },
      // ...
    }
  }
}

A modo de ejemplo, los resultados muestran que https://web.dev/fast/ tiene un 85% de experiencias de LCP "buenas" y un percentil 75 de 1,947 milisegundos, lo que es ligeramente 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, si se consulta la URL https://web.dev/fast/#measure-performance-in-the-field, se obtendrán datos para 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.

Consulta por factor de forma

Las experiencias del usuario pueden variar significativamente según las optimizaciones del sitio web, las condiciones de la red y los dispositivos de los usuarios. Para comprender mejor estas diferencias, desglosa el rendimiento de la URL y el origen con la dimensión formFactor de la API de CrUX.

La API admite tres valores de factor de forma explícitos: 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 únicamente a esas experiencias del usuario. En este ejemplo, se muestra cómo consultar la API por factor de forma mediante 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 la API de CrUX en busca de datos específicos de factores de forma con JavaScript, llama a la función CrUXApiUtil.query con los parámetros url y formFactor en el 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 la solicitud formFactor para confirmar que solo se incluyan las experiencias telefónicas.

Recuerda de la sección anterior que el 85% de las experiencias del usuario en esta página tenían un LCP "bueno". Compara estos valores con las experiencias específicas para teléfonos, de las cuales solo el 78% se consideran "buenas". El percentil 75 también es más lento en las experiencias con teléfonos, 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 de 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 web esenciales (LCP, FID, 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',
    'first_input_delay',
    '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}).`)
  });
}

Los resultados muestran que esta página aprueba las evaluaciones de las Métricas web esenciales para 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 first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

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

¿Qué sigue?

Las funciones incluidas en la versión inicial de la API de CrUX solo muestran algunos de los tipos de estadísticas que se pueden obtener 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, como 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 explora más aplicaciones de ejemplo. Esperamos que lo pruebes y nos encantaría recibir cualquier pregunta o comentario que tengas, así que comunícate con nosotros en el foro de debate de CrUX. Para mantenerte al tanto de todo lo que planificamos para la API de CrUX, suscríbete al foro de anuncios de CrUX o síguenos en Twitter (@ChromeUXReport).