Uso de la API de informes de UX de Chrome

los Informe de UX de Chrome El conjunto de datos (CrUX) representa cómo los usuarios de Chrome en el mundo real experimentan los destinos populares en la web. Desde 2017, cuando el conjunto de datos consultables se lanzó por primera vez en BigQuery, los datos de campo de CrUX se han integrado en herramientas para desarrolladores como PageSpeed ​​Insights, CrUX Dashboard y Search Console. Informe Core Web Vitals, lo que permite a los desarrolladores medir y monitorear fácilmente las experiencias de los usuarios reales. La pieza que ha faltado todo este tiempo ha sido una herramienta que proporciona acceso gratuito y RESTful a los datos de CrUX mediante programación. Para ayudar a cerrar esa brecha, nos complace anunciar el lanzamiento de las nuevas API de informes de UX de Chrome!

Esta API se ha creado con el objetivo de proporcionar a los desarrolladores un acceso sencillo, rápido y completo a los datos de CrUX. La API de CrUX solo informa campo datos de la experiencia del usuario, a diferencia de los existentes API de PageSpeed ​​Insights, que también informa laboratorio datos de las auditorías de rendimiento de Lighthouse. La API de CrUX está optimizada y puede servir rápidamente los datos de la experiencia del usuario, 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 que más importan (los elementos básicos de Web Vitals), la API de CrUX audita y supervisa la pintura de contenido más grande (LCP), el retraso de la primera entrada (FID) y el cambio de diseño acumulativo (CLS) en ambos el origen y el nivel de URL.

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

Consulta de datos de origen

Los orígenes en el conjunto de datos CrUX abarcan todas las experiencias subyacentes a nivel de página. El siguiente ejemplo demuestra cómo consultar la API de CrUX para obtener los datos de la experiencia del usuario de un origen utilizando cURL en la línea de comando.

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"}'

Ejecute esta consulta de forma interactiva en el Explorador de API de CrUX.

los curl El comando consta de tres partes:

1. El punto final de la URL de la API, incluida la clave API privada de la persona que llama.
2. los Content-Type: application/json encabezado, que indica que el cuerpo de la solicitud contiene JSON.
3. El codificado JSON cuerpo de solicitud, especificando el https://web.dev origen.

Para hacer lo mismo en JavaScript, use el CrUXApiUtil utilidad, que realiza la llamada a la API y devuelve la respuesta decodificada.

const CrUXApiUtil = {};

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;
  });
};

Reemplazar [YOUR_API_KEY] con tu llave. A continuación, llame al CrUXApiUtil.query función y pasar en el cuerpo de solicitud objeto.

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étrica que representa la distribución de experiencias de usuario. Las métricas de distribución son los intervalos de histogramas y los 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
        }
      },
      
    }
  }
}

los start y end propiedades del histogram El objeto representa el rango de valores que experimentan los usuarios para la métrica dada. los density La propiedad representa la proporción de experiencias de usuario dentro de ese rango. En este ejemplo, el 79% de las experiencias de usuario de LCP en todas las páginas web.dev están por debajo de los 2500 milisegundos, que es el umbral de LCP «bueno». los percentiles.p75 El valor significa que el 75% de las experiencias de los usuarios en esta distribución son menos de 2216 milisegundos. Obtenga más información sobre la estructura de respuesta en el cuerpo de respuesta documentación.

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 verifique que el origen solicitado sea navegable públicamente. Puede probar esto ingresando el origen en la barra de URL de su navegador y comparándolo con la URL final después de cualquier redirección. Los problemas comunes incluyen agregar u omitir innecesariamente el subdominio y usar el protocolo HTTP incorrecto.

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

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

Si el origen solicitado es la versión navegable, este error también puede ocurrir si el origen tiene un número insuficiente de muestras. Todos los orígenes y URL 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 URL deben ser rastreable públicamente. Referirse a Metodología CrUX para obtener más información sobre cómo se incluyen los sitios web en el conjunto de datos.

Consulta de datos de URL

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

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 url parámetro para especificar la página a buscar.

Para consultar datos de URL de la API CrUX en JavaScript, llame al CrUXApiUtil.query función usando el url parámetro 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 CrUX, la API devolverá una respuesta codificada en JSON como la que se muestra a continuación.

{
  "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
        }
      },
      
    }
  }
}

Fiel a su estilo, 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 de todo el origen.

Normalización de URL

La API de CrUX puede normalizar las URL solicitadas para que coincidan mejor con la lista de URL conocidas. Por ejemplo, consultar la URL https://web.dev/fast/#measure-performance-in-the-field resultará en datos para https://web.dev/fast/ debido a la normalización. Cuando esto sucede, un urlNormalizationDetails El objeto se incluirá 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"
  }
}

Aprender más acerca de Normalización de URL en la documentación de CrUX.

Consulta por factor de forma

Las experiencias de los usuarios 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, profundice en el origen y el rendimiento de la URL mediante el formFactor dimensión de la API CrUX.

La API admite tres valores de factor de forma explícitos: DESKTOP, PHONEy TABLET. Además del origen o URL, especifique uno de estos valores en el cuerpo de solicitud para restringir los resultados solo a las experiencias de los usuarios. El siguiente ejemplo demuestra cómo consultar la API por factor de forma usando 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 para datos específicos de factor de forma usando JavaScript, llame al CrUXApiUtil.query función usando el url y formFactor parámetros 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);
});

Omitiendo el formFactor parámetro es equivalente 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
        }
      },
    
    }
  }
}

los key el campo de la respuesta hará eco de la formFactor Solicite la configuración para confirmar que solo se incluyen las experiencias telefónicas.

Recuerde de la sección anterior que el 85% de las experiencias de los usuarios en esta página tenían un LCP «bueno». Compare 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 telefónicas, pasando de 1.947 milisegundos a 2.366 milisegundos. La segmentación por factor de forma tiene el potencial de resaltar disparidades más extremas en las experiencias de los usuarios.

Evaluación del desempeño de Core Web Vitals

El programa Core Web Vitals define objetivos que ayudan a determinar si una experiencia de usuario o una distribución de experiencias puede considerarse «buena». En el siguiente ejemplo, usamos la API CrUX y la CrUXApiUtil.query función para evaluar si la distribución de las métricas de Core Web Vitals (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) {
  
  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;
    
    
    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 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 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).

Combinado con una forma automatizada de monitorear los resultados de la API, los datos de CrUX se pueden usar para garantizar que las experiencias del usuario conseguir rápido y mantente rápido. Para obtener más información sobre Core Web Vitals y cómo medirlos, consulte Web Vitals y Herramientas para medir Core Web Vitals.

¿Que sigue?

Las características incluidas en la versión inicial de la API de CrUX solo arañan la superficie de los tipos de información que son posibles con CrUX. Los usuarios del conjunto de datos CrUX en BigQuery pueden estar familiarizados con algunas de las funciones más avanzadas, que incluyen:

• Métricas adicionales
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• Dimensiones adicionales
  • mes
  • país
  • tipo de conexión efectiva (ECT)
• Granularidad adicional
  • histogramas detallados
  • más percentiles

Con el tiempo, esperamos integrar más de estas características con la facilidad de uso y los precios gratuitos de la API de CrUX para permitir nuevas formas de explorar los datos y descubrir información sobre el estado de las experiencias de los usuarios en la web.

Echa un vistazo al oficial Documentos de la API de CrUX a adquirir su clave API y explorar más aplicaciones de ejemplo. Esperamos que lo pruebes y nos encantaría escuchar cualquier pregunta o comentario que puedas tener, así que comunícate con nosotros en el Foro de discusión de CrUX. Y para estar al día de todo lo que hemos planeado para la API de CrUX, suscríbete al Foro de anuncios de CrUX o síguenos en Twitter en @ChromeUXReport.