Cómo usar la API de CrUX

Obtén información para usar la API de Chrome UX Report y obtener acceso a los datos de la experiencia de los usuarios reales en millones de sitios web.

Rick Viscomi

Shane Exterkamp

El conjunto de datos del Informe de UX de Chrome (CrUX) representa la experiencia que tienen los usuarios de Chrome en el mundo real con 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 Core Web Vitals de Search Console, lo que permite a los desarrolladores medir y supervisar las experiencias de los usuarios reales. Lo que faltaba todo este tiempo era una herramienta que proporcionara acceso RESTful y gratuito a los datos de CrUX de forma programática. Para ayudar a cerrar esa brecha, nos complace anunciar el lanzamiento de la nueva API de informes de UX de Chrome.

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 experiencia del usuario de campo, a diferencia de la API de PageSpeed Insights existente, que también informa datos de laboratorio de las auditorías de rendimiento de Lighthouse. La API de CrUX está optimizada y puede entregar datos de experiencia del usuario con rapidez, lo que la hace 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 la pintura más grande con contenido (LCP), la interacción hasta la siguiente pintura (INP) y el desplazamiento del diseño acumulativo (CLS) a nivel del origen y de la URL.

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

Prueba la API en esta página

Pruébalo

Cómo consultar datos de origen

Los orígenes del 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 los datos de 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"}'

Nota: Todas las solicitudes a la API deben proporcionar un valor para el parámetro key. [YOUR_API_KEY] en el ejemplo anterior se deja como marcador de posición. Obtén tu propia clave de API privada 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 llamador
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 obtener más funciones, como el historial y la compatibilidad con 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 intervalos de histograma 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 del usuario dentro de ese rango. En este ejemplo, el 79% de las experiencias del usuario de LCP en todas las páginas de web.dev son inferiores a 2,500 milisegundos, que es el umbral de LCP "bueno". El valor de percentiles.p75 significa que el 75% de las experiencias del usuario en esta distribución son inferiores a 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 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 sea navegable 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 incorrectamente el protocolo http:// y el subdominio www..

Listo

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

Se puede navegar por este origen de forma pública.

Si el origen solicitado es la versión navegable, este error también puede ocurrir si el origen tiene una cantidad insuficiente 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 ser indexables de forma pública. 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.

Cómo consultar datos de URLs

Ya sabes 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 los datos de URL de 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
        }
      },
      // ...
    }
  }
}

Tal como se esperaba, los resultados muestran que https://web.dev/fast/ tiene un 85% de experiencias de LCP "buenas" y un percentil 75 de 1,947 milisegundos, que es ligeramente mejor que la distribución en todo el origen.

Normalización de URLs

La API de CrUX puede normalizar las URLs solicitadas para que coincidan mejor con la lista de URLs conocidas. Por ejemplo, si consultas la URL https://web.dev/fast/#measure-performance-in-the-field, se mostrarán 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.

Cómo consultar 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 de forma significativa 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 del origen y la URL 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 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 la API de CrUX en busca de datos específicos del factor 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 de 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 incluyen experiencias de 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 generar errores de "no encontrado" más frecuentes, especialmente cuando se consultan URLs menos populares o el tipo de dispositivo de tablet menos popular.

Recuerda que, en la sección anterior, se indicó que el 85% de las experiencias del usuario en esta página tenían un LCP "bueno". Compara eso con las experiencias específicas de los teléfonos, de las cuales solo el 78% se considera "buena". El percentil 75 también es más lento entre las experiencias de teléfono, ya que aumentó de 1,947 milisegundos a 2,366 milisegundos. La segmentación por factor de forma tiene el potencial de destacar 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 se puede considerar "buena". 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 y 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 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 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 son una pequeña muestra de los tipos de estadísticas que es posible 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
  • más percentiles

Consulta la documentación oficial de la API de CrUX para adquirir tu clave de API y explorar más aplicaciones de ejemplo. Esperamos que lo pruebes. Nos encantaría conocer tus preguntas o comentarios, así que comunícate con nosotros en el foro de debate de CrUX. Además, para mantenerte al tanto de todo lo que tenemos planeado para la API de CrUX, suscríbete al foro de anuncios de CrUX o síguenos en Twitter en @ChromeUXReport.