نحوه استفاده از CrUX API

با نحوه استفاده از Chrome UX Report API برای دسترسی به داده‌های تجربه کاربر واقعی در میلیون‌ها وب‌سایت آشنا شوید.

ریک ویسکومی
شین اکسترکمپ
Shane Exterkamp
X GitHub

مجموعه داده Chrome UX Report (CrUX) نشان می‌دهد که کاربران Chrome در دنیای واقعی چگونه مقاصد محبوب را در وب تجربه می‌کنند. از سال 2017، زمانی که مجموعه داده قابل پرس و جو برای اولین بار در BigQuery منتشر شد، داده‌های میدانی CrUX در ابزارهای توسعه‌دهنده مانند PageSpeed ​​Insights ، داشبورد CrUX و گزارش Core Web Vitals کنسول جستجو ادغام شده‌اند و توسعه‌دهندگان را قادر می‌سازد تا تجربیات کاربر واقعی را اندازه‌گیری و نظارت کنند. قطعه ای که در تمام این مدت گم شده است، ابزاری بوده است که دسترسی رایگان و راحت به داده های CrUX را به صورت برنامه ریزی شده فراهم می کند. برای کمک به پر کردن این شکاف، ما مشتاقیم که انتشار API گزارش Chrome UX جدید را اعلام کنیم!

این API با هدف ارائه دسترسی ساده، سریع و جامع به داده های CrUX به توسعه دهندگان ساخته شده است. CrUX API فقط داده‌های تجربه کاربری میدانی را گزارش می‌کند، برخلاف API موجود PageSpeed ​​Insights که همچنین داده‌های آزمایشگاهی را از ممیزی‌های عملکرد Lighthouse گزارش می‌کند. CrUX API ساده است و می‌تواند به سرعت داده‌های تجربه کاربر را ارائه کند، و آن را برای برنامه‌های حسابرسی بلادرنگ مناسب می‌کند.

برای اطمینان از اینکه توسعه‌دهندگان به تمام معیارهایی که بیشترین اهمیت را دارند - Core Web Vitals - دسترسی دارند، 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 را مشخص می کند.

برای انجام همین کار در جاوا اسکریپت، از ابزار 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 میلی ثانیه است. درباره ساختار پاسخ در مستندات بدنه پاسخ بیشتر بیاموزید.

خطاها

وقتی 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 برای مشخص کردن صفحه برای جستجو استفاده می کند.

برای پرس و جو داده های URL از CrUX API در جاوا اسکریپت، تابع 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

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

درباره عادی سازی URL در مستندات CrUX بیشتر بیاموزید.

پرس و جو بر اساس فرم فاکتور

تجربیات کاربر بسته به بهینه سازی وب سایت، شرایط شبکه و دستگاه های کاربران می تواند به طور قابل توجهی متفاوت باشد. برای درک بهتر این تفاوت‌ها، با استفاده از بعد formFactor CrUX API، عملکرد مبدا و URL را بررسی کنید.

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 برای داده های خاص فاکتور فرم با استفاده از جاوا اسکریپت، تابع 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 را می‌توان برای اطمینان از سریع بودن تجربه‌های کاربر واقعی و سریع ماندن استفاده کرد. برای اطلاعات بیشتر در مورد Core Web Vitals و نحوه اندازه‌گیری آن‌ها، Web Vitals و ابزارهای اندازه‌گیری Core Web Vitals را بررسی کنید.

بعدش چی؟

ویژگی‌های موجود در نسخه اولیه CrUX API فقط سطح بینش‌هایی را که با CrUX امکان‌پذیر است، خراش می‌دهند. کاربران مجموعه داده CrUX در BigQuery ممکن است با برخی از ویژگی های پیشرفته تر از جمله آشنا باشند:

  • معیارهای اضافی
    • 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 دنبال کنید.