Как использовать API Crux

Узнайте, как использовать Chrome UX Report API, чтобы получить доступ к реальным данным об опыте пользователей на миллионах веб-сайтов.

Рик Вискоми
Шейн Экстеркамп
Shane Exterkamp
X GitHub

Набор данных Chrome UX Report (CrUX) показывает, как реальные пользователи Chrome взаимодействуют с популярными местами в Интернете. С 2017 года, когда набор запрашиваемых данных был впервые выпущен на BigQuery , данные полей из CrUX были интегрированы в инструменты разработчика, такие как PageSpeed ​​Insights , панель управления CrUX и отчет Core Web Vitals в Search Console, что позволяет разработчикам измерять и отслеживать взаимодействие с реальными пользователями. Частью, которой не хватало все это время, был инструмент, который обеспечивает бесплатный и RESTful доступ к данным CrUX программным способом. Чтобы восполнить этот пробел, мы рады объявить о выпуске совершенно нового Chrome UX Report API !

Этот API был создан с целью предоставить разработчикам простой, быстрый и комплексный доступ к данным CrUX. API CrUX сообщает только данные об опыте работы пользователей на местах , в отличие от существующего API PageSpeed ​​Insights , который также сообщает лабораторные данные аудита производительности Lighthouse. API CrUX оптимизирован и может быстро предоставлять данные о пользовательском опыте, что делает его идеально подходящим для приложений аудита в реальном времени.

Чтобы гарантировать, что разработчики имеют доступ ко всем наиболее важным метрикам — основным веб-показателям — API CrUX проверяет и отслеживает наибольшую отрисовку контента (LCP), взаимодействие с следующей отрисовкой (INP) и совокупный сдвиг макета (CLS) на всех этапах. как источник, так и уровень URL.

Итак, давайте углубимся и посмотрим, как его использовать!

Попробуйте API на этой странице

Попробуйте!

Данные об источнике запроса

Источники в наборе данных CrUX охватывают все базовые возможности уровня страницы. В следующем примере показано, как запросить у CrUX API данные об опыте пользователя источника с помощью cURL в командной строке.

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

Команда curl состоит из трех частей:

  1. Конечная точка URL API, включая закрытый ключ API вызывающей стороны.
  2. Заголовок Content-Type: application/json , указывающий, что тело запроса содержит JSON.
  3. Тело запроса в формате JSON с указанием источника https://web.dev .

Чтобы сделать то же самое в JavaScript, используйте утилиту CrUXApiUtil , которая выполняет вызов API и возвращает декодированный ответ (см. также наш вариант Github для получения дополнительных функций, включая поддержку истории и пакетной обработки).

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

Замените [YOUR_API_KEY] своим ключом . Затем вызовите функцию CrUXApiUtil.query и передайте объект тела запроса .

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

Если данные для этого источника существуют, ответ API представляет собой объект в кодировке JSON, содержащий метрики, представляющие распределение пользовательского опыта. Метриками распределения являются ячейки гистограммы и процентили.

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

Свойства start и end объекта histogram представляют диапазон значений, которые пользователи видят для данной метрики. Свойство density представляет долю пользовательского опыта в этом диапазоне. В этом примере 79% действий пользователей LCP на всех страницах web.dev составляют менее 2500 миллисекунд, что является « хорошим » порогом LCP. Значение percentiles.p75 означает, что 75% времени взаимодействия с пользователем в этом дистрибутиве длится менее 2216 миллисекунд. Дополнительные сведения о структуре ответа см. в документации по телу ответа .

Ошибки

Когда API CrUX не имеет данных для данного источника, он отвечает сообщением об ошибке в формате JSON:

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

Чтобы устранить эту ошибку, сначала убедитесь, что запрошенный источник является общедоступным. Вы можете проверить это, введя источник в адресную строку браузера и сравнив его с конечным URL-адресом после любых перенаправлений. Распространенные проблемы включают излишнее добавление или исключение поддомена и использование неправильного протокола HTTP.

Ошибка 
{"origin": "http://www.web.dev"}

Этот источник неправильно включает протокол http:// и www. поддомен.

Успех 
{"origin": "https://web.dev"}

Этот источник общедоступен.

Если запрошенный источник является навигационной версией, эта ошибка также может возникнуть, если источник имеет недостаточное количество образцов. Все источники и URL-адреса, включенные в набор данных, должны иметь достаточное количество образцов для анонимизации отдельных пользователей. Кроме того, источники и URL-адреса должны быть публично индексируемыми . Обратитесь к методологии CrUX, чтобы узнать больше о том, как веб-сайты включаются в набор данных.

Запросить данные URL

Вы видели, как запросить у CrUX API общее впечатление от пользователя в источнике. Чтобы ограничить результаты конкретной страницей, используйте параметр запроса 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/"}'

Эта команда cURL аналогична примеру источника, за исключением того, что в теле запроса используется параметр url для указания страницы для поиска.

Чтобы запросить данные URL-адреса из CrUX API в JavaScript, вызовите функцию CrUXApiUtil.query используя параметр url в теле запроса.

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

Если данные для этого URL-адреса существуют в наборе данных CrUX, API вернет ответ в формате JSON. Например 

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

Как и следовало ожидать, результаты показывают, что https://web.dev/fast/ имеет 85% «хороших» результатов LCP и 75-й процентиль, равный 1947 миллисекундам, что немного лучше, чем распределение по всему источнику.

Нормализация URL-адресов

API CrUX может нормализовать запрошенные URL-адреса, чтобы лучше соответствовать списку известных URL-адресов. Например, запрос URL-адреса https://web.dev/fast/#measure-performance-in-the-field -the-field приведет к получению данных для https://web.dev/fast/ из-за нормализации. В этом случае в ответ будет включен объект urlNormalizationDetails . 

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

Узнайте больше о нормализации URL-адресов в документации CrUX.

Запрос по форм-фактору

Пользовательский опыт может существенно различаться в зависимости от оптимизации веб-сайта, условий сети и устройств пользователей. Чтобы лучше понять эти различия, углубитесь в происхождение и производительность URL-адресов, используя измерение formFactor API CrUX.

API поддерживает три явных значения форм-фактора: DESKTOP , PHONE и TABLET . Помимо источника или URL-адреса, укажите одно из этих значений в тексте запроса , чтобы ограничить результаты только теми пользователями. В этом примере показано, как запросить API по форм-фактору с помощью 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"}'

Чтобы запросить у CrUX API данные, специфичные для форм-фактора, с помощью JavaScript, вызовите функцию CrUXApiUtil.query используя параметры url и formFactor в теле запроса. 

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

Отсутствие параметра formFactor эквивалентно запросу данных для всех форм-факторов вместе взятых. 

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

key поле ответа вернет конфигурацию запроса formFactor , чтобы подтвердить, что включены только возможности телефона.

Вспомните из предыдущего раздела, что 85% пользователей на этой странице имели «хороший» LCP. Сравните это с впечатлениями от конкретных телефонов, из которых только 78% считаются «хорошими». 75-й процентиль также медленнее при использовании телефона: с 1947 миллисекунд до 2366 миллисекунд. Сегментация по форм-фактору может выявить более серьезные различия в пользовательском опыте.

Оцените производительность Core Web Vitals

Программа Core Web Vitals определяет цели, которые помогают определить, можно ли считать пользовательский опыт или распространение опыта «хорошим». В следующем примере мы используем CrUX API и функцию CrUXApiUtil.query , чтобы оценить, является ли распределение на веб-странице показателей Core Web Vitals (LCP, INP, CLS) «хорошим». 

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

Результаты показывают, что эта страница проходит оценку Core Web Vitals по всем трем показателям. 

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).

В сочетании с автоматизированным способом мониторинга результатов API данные из CrUX можно использовать для обеспечения быстрого и быстрого взаимодействия с реальными пользователями. Для получения дополнительной информации об основных веб-показателях и способах их измерения ознакомьтесь с веб-показателями и инструментами для измерения основных веб-показателей .

Что дальше?

Функции, включенные в первоначальную версию CrUX API, лишь поверхностно отражают те идеи, которые возможны с помощью CrUX. Пользователи набора данных CrUX в BigQuery могут быть знакомы с некоторыми более продвинутыми функциями, включая:

  • Дополнительные метрики
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Дополнительные размеры
    • month
    • country
    • effective connection type (ECT)
  • Дополнительная детализация
    • подробные гистограммы
    • больше процентилей

Ознакомьтесь с официальной документацией по API CrUX, чтобы получить ключ API и изучить дополнительные примеры приложений. Мы надеемся, что вы попробуете, и будем рады услышать любые ваши вопросы или отзывы, поэтому свяжитесь с нами на дискуссионном форуме CrUX . А чтобы быть в курсе всего, что мы запланировали для CrUX API, подпишитесь на форум объявлений CrUX или следите за нами в Твиттере @ChromeUXReport .