이 페이지는 Cloud Translation API를 통해 번역되었습니다.

CrUX API 사용 방법

Chrome UX 보고서 API를 사용하여 수백만 개의 웹사이트에서 실제 사용자 환경 데이터에 액세스하는 방법을 알아보세요.

Rick Viscomi

Shane Exterkamp

Chrome UX 보고서 (CrUX) 데이터 세트는 실제 Chrome 사용자가 웹에서 인기 있는 사이트를 이용하는 방식을 나타냅니다. 쿼리 가능한 데이터 세트가 BigQuery에 처음 출시된 2017년 이후 CrUX의 필드 데이터가 PageSpeed Insights, CrUX 대시보드, Search Console의 Core Web Vitals 보고서와 같은 개발자 도구에 통합되어 개발자가 실제 사용자 환경을 측정하고 모니터링할 수 있게 되었습니다. 그동안 누락된 부분은 CrUX 데이터에 프로그래매틱 방식으로 무료로 RESTful 액세스를 제공하는 도구였습니다. 이러한 격차를 해소하기 위해 새로운 Chrome UX Report API를 출시하게 되어 기쁩니다.

이 API는 개발자가 CrUX 데이터에 간단하고 빠르며 포괄적으로 액세스할 수 있도록 하기 위해 빌드되었습니다. CrUX API는 Lighthouse 성능 감사의 실험실 데이터도 보고하는 기존 PageSpeed Insights API와 달리 필드 사용자 환경 데이터만 보고합니다. CrUX API는 간소화되어 있으며 사용자 환경 데이터를 빠르게 제공할 수 있으므로 실시간 감사 애플리케이션에 적합합니다.

개발자가 가장 중요한 모든 측정항목인 Core Web Vitals에 액세스할 수 있도록 CrUX API는 출처 및 URL 수준에서 최대 콘텐츠 페인트 (LCP), 다음 페인트에 대한 상호작용 (INP), 누적 레이아웃 이동 (CLS)을 감사하고 모니터링합니다.

그럼 사용 방법을 자세히 알아보겠습니다.

이 페이지에서 API 사용해 보기

사용해 보기

출처 데이터 쿼리

CrUX 데이터 세트의 출처는 모든 기본 페이지 수준 환경을 포함합니다. 다음 예에서는 명령줄에서 cURL을 사용하여 CrUX API에 액세스하여 출처의 사용자 환경 데이터를 쿼리하는 방법을 보여줍니다.

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

참고: 모든 API 요청은 key 매개변수의 값을 제공해야 합니다. 이전 예의 [YOUR_API_KEY]는 자리표시자로 남겨집니다. CrUX API 문서에 설명된 대로 자체 비공개 CrUX API 키를 가져옵니다.

curl 명령어는 다음 세 부분으로 구성됩니다.

호출자의 비공개 API 키를 포함한 API의 URL 엔드포인트입니다.
요청 본문에 JSON이 포함되어 있음을 나타내는 Content-Type: application/json 헤더
https://web.dev 출처를 지정하는 JSON으로 인코딩된 요청 본문입니다.

JavaScript에서 동일한 작업을 수행하려면 API를 호출하고 디코딩된 응답을 반환하는 CrUXApiUtil 유틸리티를 사용하세요. 기록 및 일괄 지원을 비롯한 더 많은 기능은 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
        }
      },
      // ...
    }
  }
}

histogram 객체의 start 및 end 속성은 사용자가 지정된 측정항목에서 경험하는 값의 범위를 나타냅니다. density 속성은 해당 범위 내 사용자 경험의 비율을 나타냅니다. 이 예시에서 모든 web.dev 페이지의 LCP 사용자 환경 중 79% 가 '좋음' LCP 기준점인 2,500밀리초 미만입니다. percentiles.p75 값은 이 분포에서 사용자 환경의 75% 가 2,216밀리초 미만이라는 의미입니다. 응답 본문 문서에서 응답 구조에 대해 자세히 알아보세요.

오류

CrUX API에 지정된 출처에 대한 데이터가 없으면 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 매개변수를 사용하여 조회할 페이지를 지정한다는 점을 제외하고 출처 예와 유사합니다.

JavaScript에서 CrUX API의 URL 데이터를 쿼리하려면 요청 본문에서 url 매개변수를 사용하여 CrUXApiUtil.query 함수를 호출합니다.

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

CrUX 데이터 세트에 이 URL의 데이터가 있으면 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번째 백분위수는 1,947밀리초로 출처 전체 배포보다 약간 나았습니다.

URL 정규화

CrUX API는 알려진 URL 목록과 더 잘 일치하도록 요청된 URL을 정규화할 수 있습니다. 예를 들어 URL https://web.dev/fast/#measure-performance-in-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"
  }
}

CrUX 문서에서 URL 정규화에 대해 자세히 알아보세요.

폼 팩터별 쿼리

사용자 환경은 웹사이트 최적화, 네트워크 상태, 사용자 기기에 따라 크게 달라질 수 있습니다. 이러한 차이를 더 잘 이해하려면 CrUX API의 formFactor 측정기준을 사용하여 출처 및 URL 성능을 드릴다운하세요.

이 API는 DESKTOP, PHONE, TABLET의 세 가지 명시적 폼 팩터 값을 지원합니다. 출처 또는 URL 외에도 요청 본문에 이러한 값 중 하나를 지정하여 결과를 해당 사용자 환경으로만 제한합니다. 이 예에서는 cURL을 사용하여 폼 팩터별로 API를 쿼리하는 방법을 보여줍니다.

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

JavaScript를 사용하여 CrUX API에 폼 팩터별 데이터를 쿼리하려면 요청 본문에서 url 및 formFactor 매개변수를 사용하여 CrUXApiUtil.query 함수를 호출합니다.

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번째 백분위수도 느려져 1,947밀리초에서 2,366밀리초로 증가했습니다. 폼 팩터별로 분류하면 사용자 환경의 극심한 불균형을 강조할 수 있습니다.

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/articles/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의 데이터를 사용하면 실제 사용자 환경이 빠르게 시작되고 빠르게 유지되도록 할 수 있습니다. Core Web Vitals 및 측정 방법에 관한 자세한 내용은 웹 바이탈 및 Core Web Vitals를 측정하는 도구를 참고하세요.

다음 단계

CrUX API의 초기 버전에 포함된 기능은 CrUX로 얻을 수 있는 유형의 통계에 대한 일부만 보여줍니다. BigQuery의 CrUX 데이터 세트 사용자는 다음과 같은 고급 기능에 익숙할 수 있습니다.

추가 측정항목
- first_paint
- dom_content_loaded
- onload
- time_to_first_byte
- notification_permissions
추가 측정기준
- month
- country
- effective connection type (ECT)
추가 세부사항
- 상세 히스토그램
- 백분위수 더보기

공식 CrUX API 문서를 확인하여 API 키를 가져오고 더 많은 애플리케이션 예시를 살펴보세요. 사용해 보시기 바라며, 궁금한 점이나 의견이 있으면 CrUX 토론 포럼에서 알려주세요. CrUX API에 대해 계획된 모든 사항을 최신 상태로 유지하려면 CrUX 공지사항 포럼을 구독하거나 트위터에서 @ChromeUXReport를 팔로우하세요.