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

CrUX API 사용 방법

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

Rick Viscomi

Shane Exterkamp

Chrome UX 보고서 (CrUX) 데이터 세트는 실제 Chrome 사용자가 웹에서 인기 있는 웹사이트를 경험하는 방식을 보여줍니다. 쿼리 가능한 데이터 세트가 BigQuery에서 처음 출시된 2017년부터 CrUX의 필드 데이터가 PageSpeed Insights, CrUX Dashboard, 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)을 감사하고 모니터링합니다.

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

원본 데이터 쿼리

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 엔드포인트입니다.
Content-Type: application/json 헤더: 요청 본문에 JSON이 포함되어 있음을 나타냅니다.
https://web.dev 출처를 지정하는 JSON으로 인코딩된 요청 본문입니다.

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

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

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

결과에 이 페이지가 3가지 측정항목 모두에 대한 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 및 측정 방법에 관한 자세한 내용은 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)
추가 세부사항
- 상세한 히스토그램
- 백분위수 증가

API 키를 획득하려면 공식 CrUX API 문서를 확인하고 더 많은 예시 애플리케이션을 살펴보세요. 사용해 보시고 질문이나 의견이 있으면 언제든지 CrUX 토론 포럼에서 문의해 주세요. CrUX API와 관련하여 Google이 계획한 모든 최신 소식을 확인하려면 CrUX 공지 포럼을 구독하거나 Twitter에서 @ChromeUXReport를 팔로우하세요.