CrUX API

CrUX API는 페이지 및 출처 세부사항에서 집계된 실제 사용자 환경 데이터에 짧은 지연 시간으로 액세스할 수 있도록 지원합니다.

사용해 보기

일반적인 사용 사례

CrUX API를 사용하면 'https://example.com 출처의 측정항목 가져오기'와 같은 특정 URI의 사용자 환경 측정항목을 쿼리할 수 있습니다.

CrUX API 키

CrUX API를 사용하려면 Chrome UX Report API 사용을 위해 프로비저닝된 Google Cloud API 키가 필요합니다.

API 키 획득 및 사용

또는 사용자 인증 정보 페이지에서 만듭니다.

API 키가 있으면 애플리케이션은 모든 요청 URL에 쿼리 매개변수 key=yourAPIKey를 추가할 수 있습니다.

API 키는 URL에 포함하기에 안전합니다. 인코딩이 전혀 필요하지 않습니다.

쿼리 예시를 참조하세요.

데이터 모델

이 섹션에서는 요청 및 응답의 데이터 구조를 자세히 설명합니다.

녹화

페이지 또는 사이트에 관한 개별 정보입니다. 레코드에는 식별자 및 특정 측정기준 조합에 관한 데이터가 포함될 수 있습니다. 레코드에는 하나 이상의 측정항목에 관한 데이터가 포함될 수 있습니다.

식별자

식별자는 조회해야 하는 레코드를 지정합니다. CrUX에서 이러한 식별자는 웹페이지와 웹사이트입니다.

출발지

식별자가 출처인 경우 해당 출처의 모든 페이지에 있는 모든 데이터가 함께 집계됩니다. 예를 들어 http://www.example.com 출처에 이 사이트맵에 배치된 페이지가 있다고 가정해 보겠습니다.

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

즉, 출처가 http://www.example.com로 설정된 Chrome UX 보고서를 쿼리하면 http://www.example.com/, http://www.example.com/foo.html, http://www.example.com/bar.html의 데이터가 함께 집계되어 반환됩니다. 이는 모두 해당 출처에 속한 페이지이기 때문입니다.

URL

식별자가 URL인 경우 해당 URL의 데이터만 반환됩니다. http://www.example.com 출처 사이트맵을 다시 살펴보겠습니다.

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

식별자가 http://www.example.com/foo.html 값의 URL로 설정된 경우 해당 페이지의 데이터만 반환됩니다.

크기

측정기준은 레코드가 집계되는 특정 데이터 그룹을 식별합니다. 예를 들어 PHONE의 폼 팩터는 레코드에 모바일 기기에서 발생한 로드에 관한 정보가 포함되어 있음을 나타냅니다. 각 측정기준에는 특정 개수의 값이 있으며, 측정기준을 지정하지 않으면 측정기준이 모든 값에 대해 집계됩니다. 예를 들어 폼 팩터를 지정하지 않으면 레코드에 모든 폼 팩터에서 발생한 로드에 관한 정보가 포함됩니다.

폼 팩터

최종 사용자가 페이지로 이동하는 데 사용한 기기 클래스입니다. PHONE, TABLET, DESKTOP로 분할된 일반적인 기기 클래스입니다.

측정항목

측정항목은 히스토그램, 백분위수, 분수로 통계 집계로 보고됩니다.

부동 소수점 값은 소수점 이하 4자리로 반올림됩니다. cumulative_layout_shift 측정항목은 문자열로 인코딩된 배정밀도 부동 소수점이므로 부동 소수점으로 간주되지 않으며 문자열 내에서 소수점 이하 2자리로 보고됩니다.

히스토그램

측정항목이 히스토그램으로 표현되면 해당 측정항목의 특정 범위에 속하는 페이지 로드 비율이 표시됩니다.

예시 측정항목의 3개 구간 히스토그램은 다음과 같습니다.

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

이 데이터는 페이지 로드의 38.18% 에서 예시 측정항목이 0ms와 1,000ms 사이에 측정되었음을 나타냅니다. 측정항목의 단위는 이 히스토그램에 포함되지 않으며, 이 경우 밀리초로 가정합니다.

또한 페이지 로드의 49.91% 는 측정항목 값이 1,000ms~3,000ms이고 11.92%는 3,000ms보다 큽니다.

백분위수

측정항목에는 추가 분석에 유용할 수 있는 백분위수가 포함될 수도 있습니다. 해당 측정항목의 지정된 백분위수에 대한 특정 측정항목 값이 보고됩니다. 이러한 값은 최종 구간 데이터가 아닌 사용 가능한 전체 데이터를 기반으로 하므로 최종 구간 히스토그램을 기반으로 한 보간된 백분위수와 일치하지 않을 수 있습니다.

{
  "percentiles": {
    "p75": 2063
  }
}

이 예시에서는 페이지 로드의 75% 이상이 측정항목 값 <= 2063으로 측정되었습니다.

분수

분수는 특정 방식으로 라벨을 지정할 수 있는 페이지 로드의 비율을 나타냅니다. 이 경우 측정항목 값은 이러한 라벨입니다.

예를 들어 form_factors 측정항목은 지정된 쿼리가 적용되는 폼 팩터 (또는 기기)의 분석을 나열하는 fractions 객체로 구성됩니다.

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

이 경우 페이지 로드의 3.77% 는 데스크톱에서, 2.88% 는 태블릿에서, 93.35% 는 휴대전화에서 측정되어 총 100% 가 됩니다.

측정항목 값 유형

BigQuery 측정항목 이름 매핑

수집 기간

2022년 10월부터 CrUX API에는 집계 기간의 시작일과 종료일을 나타내는 firstDate 및 endDate 필드가 있는 collectionPeriod 객체가 포함됩니다. 예를 들면 다음과 같습니다.

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

이를 통해 데이터를 더 잘 이해하고 해당 날짜에 데이터가 업데이트되었는지 또는 어제와 동일한 데이터를 반환하는지 확인할 수 있습니다.

수집 기간은 PageSpeed Insights에서도 확인할 수 있습니다.

또한 데이터가 전체 28일이 아닌 경우 (예: 페이지가 28일 전에 출시된 경우)에도 collectionPeriod에는 항상 28일이 표시됩니다. collectionPeriod는 CrUX 데이터가 집계된 기간이며, 반드시 데이터가 나타내는 기간은 아닙니다.

쿼리 예

쿼리는 POST 본문에 쿼리 데이터가 JSON 객체로 포함된 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"에 대한 POST 요청을 사용하여 JSON 객체로 제출됩니다.

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

예를 들어 다음 명령줄을 사용하여 curl에서 호출할 수 있습니다 (API_KEY을 키로 대체).

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

페이지 수준 데이터는 쿼리에서 origin 대신 url 속성을 전달하여 API를 통해 사용할 수 있습니다.

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

metrics 속성이 설정되지 않은 경우 사용 가능한 모든 측정항목이 반환됩니다.

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (요청에 formFactor가 지정되지 않은 경우에만 보고됨)
• experimental_ad_count (광고 측정항목에 포함된 페이지에 대해서만 보고됨)
• experimental_ad_density (광고 측정항목에 포함된 페이지에만 보고됨)
• experimental_ad_cpu (광고 측정항목에 포함된 페이지에만 보고됨)
• experimental_ad_kilobytes (광고 측정항목에 포함된 페이지에만 보고됨)

formFactor 값이 제공되지 않으면 모든 폼 팩터에서 값이 집계됩니다.

더 많은 예시 쿼리는 Chrome UX Report API 사용을 참고하세요.

데이터 파이프라인

CrUX 데이터 세트는 파이프라인을 통해 처리되어 데이터를 통합, 집계, 필터링한 후 API를 통해 사용할 수 있습니다.

이동 평균

Chrome UX 보고서의 데이터는 집계된 측정항목의 28일 이동 평균입니다. 즉, 특정 시점에 Chrome UX 보고서에 표시되는 데이터는 실제로 지난 28일 동안의 데이터를 합산한 것입니다.

이는 BigQuery의 CrUX 데이터 세트가 월간 보고서를 집계하는 방식과 유사합니다.

매일 업데이트

데이터는 매일 오전 4시(UTC)경에 업데이트됩니다. 업데이트 시간에 대한 서비스수준계약은 없으며, 매일 최선을 다해 실행됩니다.

스키마

POST HTTP 요청을 수락하는 CrUX API의 단일 엔드포인트가 있습니다. API는 요청된 출처 또는 페이지의 실적 데이터에 해당하는 하나 이상의 metrics가 포함된 record를 반환합니다.

HTTP 요청

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

URL은 gRPC 트랜스코딩 문법을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함되어야 합니다.

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

예를 들어 Chrome 개발자 문서 홈페이지의 데스크톱 최대 콘텐츠 페인트 값을 요청하려면 다음을 실행합니다.

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

응답 본문

요청이 성공하면 다음과 같은 구조의 record 객체와 urlNormalizationDetails가 포함된 응답이 반환됩니다.

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

예를 들어 이전 요청의 요청 본문에 대한 응답은 다음과 같습니다.

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

키

Key는 이 레코드를 고유한 것으로 식별하는 모든 측정기준을 정의합니다.

{
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

측정항목

metric는 첫 콘텐츠 페인트와 같은 단일 웹 실적 측정항목의 집계된 사용자 환경 데이터 집합입니다. 실제 Chrome 사용량의 요약 히스토그램이 bins 시리즈로 포함되거나, 특정 백분위수 데이터(예: p75)가 포함되거나, 라벨이 지정된 분수가 포함될 수 있습니다.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

또는

{
  "fractions": {
    object (Fractions)
  }
}

구간

bin는 시작부터 끝까지, 또는 끝이 지정되지 않은 경우 시작부터 양의 무한대까지의 개별 데이터 부분입니다.

구간의 시작 값과 종료 값은 구간이 나타내는 측정항목의 값 유형으로 지정됩니다. 예를 들어 첫 콘텐츠 페인트는 밀리초 단위로 측정되고 int로 노출되므로 측정항목 버킷은 시작 및 종료 유형에 int32를 사용합니다. 하지만 누적 레이아웃 이동은 단위가 없는 소수로 측정되며 문자열로 인코딩된 소수로 노출되므로 측정항목 버킷은 값 유형에 문자열을 사용합니다.

{
  "start": value,
  "end": value,
  "density": number
}

백분위수

Percentiles에는 지정된 통계 백분위수의 측정항목 합성 값이 포함됩니다. 이는 전체 사용자 수 중 특정 비율의 사용자가 경험한 측정항목 값을 추정하는 데 사용됩니다.

{
  "P75": value
}

분수

Fractions에는 합계가 약 1인 라벨이 지정된 분수가 포함됩니다. 각 라벨은 어떤 방식으로든 페이지 로드를 설명하므로 이러한 방식으로 표현된 측정항목은 숫자 값이 아닌 고유한 값을 생성하는 것으로 간주할 수 있으며 분수는 특정 고유 값이 측정된 빈도를 나타냅니다.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

히스토그램 버킷의 밀도 값과 마찬가지로 각 fraction는 0.0 <= value <= 1.0 숫자이며 합계는 약 1.0입니다.

UrlNormalization

조회 성공 가능성을 높이기 위해 URL을 정규화하는 데 사용되는 정규화 작업을 나타내는 객체입니다. 이는 제공된 url_pattern를 조회할 때 실패할 것으로 알려진 경우에 적용되는 기본적인 자동 변경사항입니다. 리디렉션 따르기와 같은 복잡한 작업은 처리되지 않습니다.

{
  "originalUrl": string,
  "normalizedUrl": string
}

비율 제한

CrUX API는 Google Cloud 프로젝트당 분당 150개의 쿼리로 제한되며 무료로 제공됩니다. 이 한도와 현재 사용량은 Google Cloud 콘솔에서 확인할 수 있습니다. 이 넉넉한 할당량은 대부분의 사용 사례에 충분하며 할당량을 늘리기 위해 비용을 지불할 수 없습니다.