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

CrUX API 사용 방법

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

Rick Viscomi

Shane Exterkamp

Chrome UX 보고서 (CrUX) 데이터 세트는 실제 Chrome 사용자가 웹에서 인기 있는 페이지를 경험하는 방식을 나타냅니다. 쿼리 가능한 데이터 세트가 BigQuery에 처음 출시된 2017년부터 CrUX의 필드 데이터는 PageSpeed Insights, CrUX 대시보드, Search Console의 코어 웹 바이탈 보고서와 같은 개발자 도구에 통합되어 개발자가 실제 사용자 환경을 측정하고 모니터링할 수 있게 해줍니다. 프로그래밍 방식으로 CrUX 데이터에 대한 RESTful 무료 액세스를 제공하는 툴이 지금까지 빠진 적이 없었습니다. 이러한 간극을 메우는 데 도움이 되도록 완전히 새로운 Chrome UX Report API를 출시한다는 소식을 전하게 되어 기쁩니다.

이 API는 개발자에게 CrUX 데이터에 대한 간단하고, 빠르고, 포괄적인 액세스를 제공하는 것을 목표로 빌드되었습니다. CrUX API는 필드 사용자 환경 데이터만 보고하지만, Lighthouse 성능 감사에서 실험실 데이터도 보고하는 기존 PageSpeed Insights API와는 다릅니다. CrUX API는 간소화되고 사용자 환경 데이터를 신속하게 제공할 수 있으므로 실시간 감사 애플리케이션에 이상적입니다.

개발자가 가장 중요한 모든 측정항목(코어 웹 바이탈)에 액세스할 수 있도록 CrUX API는 원본 및 URL 수준에서 최대 콘텐츠 렌더링 시간(LCP), 최초 입력 반응 시간(FID), 누적 레이아웃 변경(CLS)을 감사하고 모니터링합니다.

그럼 본론으로 들어가서 사용 방법을 알아보겠습니다.

원본 데이터 쿼리

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 헤더
JSON으로 인코딩된 요청 본문으로, https://web.dev 출처를 지정합니다.

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 응답은 사용자 경험의 분포를 나타내는 metrics를 포함하는 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% 가 2,500밀리초 미만이며, 이는 '양호' LCP 기준점입니다. 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);
});

이 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/의 '양호한' LCP 환경이 85%이고 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밀리초까지 느립니다. 폼 팩터별로 세분화하면 사용자 환경의 극단적인 격차를 드러낼 수 있습니다.

코어 웹 바이탈 실적 평가

코어 웹 바이탈 프로그램은 사용자 환경 또는 경험 분포가 '양호'하다고 간주할 수 있는지 판단하는 데 도움이 되는 타겟을 정의합니다. 다음 예에서는 CrUX API와 CrUXApiUtil.query 함수를 사용하여 웹페이지의 코어 웹 바이탈 측정항목 (LCP, FID, 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',
    '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}).`)
  });
}

결과는 이 페이지가 세 가지 측정항목 모두 코어 웹 바이탈 평가를 통과했음을 보여줍니다.

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

CrUX의 데이터를 자동화된 API 결과 모니터링 방법과 결합하여 실제 사용자 환경을 빠르게 향상하고 빠르게 유지할 수 있습니다. 코어 웹 바이탈과 측정 방법에 관한 자세한 내용은 웹 바이탈 및 코어 웹 바이탈 측정 도구를 참고하세요.

다음 단계

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 공지사항 포럼을 구독하거나 Twitter에서 @ChromeUXReport를 팔로우하세요.