تاريخ النشر: 7 فبراير 2023، تاريخ آخر تعديل: 11 أبريل 2025
يعرض هذا الدليل نقطة نهاية Chrome UX Report (CrUX) History API التي توفّر سلسلة زمنية لبيانات أداء الويب. يتم تعديل هذه البيانات أسبوعيًا، وتتيح لك الاطّلاع على سجلّ يمتدّ على 6 أشهر تقريبًا، مع 40 نقطة بيانات تفصل بينها مدة أسبوع.
عند استخدامها مع التحديثات اليومية من نقطة نهاية CrUX API الأصلية، يمكنك الآن الاطّلاع بسرعة على أحدث البيانات وعلى ما حدث سابقًا، ما يجعلها أداة فعّالة للاطّلاع على التغييرات في صفحات الويب بمرور الوقت.
تجربة واجهة برمجة التطبيقات على هذه الصفحة
طلب البحث من واجهة برمجة التطبيقات اليومية الخاصة بـ CrUX
للتذكير بما ورد في مقالة سابقة حول 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"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
تتضمّن هذه اللقطة قيم كثافة المدرّج التكراري وقيم النسبة المئوية لفترة جمع بيانات معيّنة مدتها 28 يومًا، في هذه الحالة، من 27 كانون الأول (ديسمبر) 2022 إلى 23 كانون الثاني (يناير) 2023.
طلب البحث من CrUX History API
لاستدعاء نقطة نهاية السجلّ، غيِّر queryRecord في عنوان URL إلى queryHistoryRecord في الأمر curl. سيكون استخدام مفتاح CrUX API نفسه كما في الطلب السابق مناسبًا.
collectionPeriodCount تحدّد عدد إدخالات السلسلة الزمنية المطلوب عرضها، والحد الأقصى هو 40. إذا لم يتم تحديدها، تكون القيمة التلقائية 25.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
يكون الشكل العام للردّ مشابهًا، ولكن يتضمّن الكثير من البيانات. بدلاً من نقطة بيانات واحدة، تتوفّر الآن سلاسل زمنية للحقول التي تحتوي على قيم الكثافة المدرّجة في المدرّج التكراري والشريحة المئوية الـ 75 (p75).
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
في هذا المثال، السلسلة الزمنية densities للمجموعة من 0 إلى 2500 ملي ثانية لمقياس سرعة عرض أكبر محتوى مرئي (LCP) هي [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. تم رصد كل من هذه الكثافات خلال الإدخال collectionPeriods المقابل. على سبيل المثال، كانت الكثافة الخامسة، 0.9183، هي الكثافة لفترة الجمع الخامسة، والتي انتهت في 3 سبتمبر 2022، وكانت 0.9187 هي الكثافة في الفترة التي انتهت في الأسبوع الذي تلا ذلك.
بعبارة أخرى، عند تفسير آخر إدخالات السلسلة الزمنية في المثال الخاص بـ https://web.dev، تبيّن أنّه في الفترة من 14 أغسطس 2022 إلى 10 سبتمبر 2022، كانت% 91.87 من عمليات تحميل الصفحات تتضمّن قيمًا لمؤشر LCP أقل من 2500 مللي ثانية، و% 5.27 تتضمّن قيمًا بين 2500 مللي ثانية و4000 مللي ثانية، و% 2.85 تتضمّن قيمًا أكبر من 4000 مللي ثانية.
وبالمثل، هناك سلسلة زمنية لقيم الشريحة المئوية الخامسة والسبعين: كانت قيمة LCP للشريحة المئوية الخامسة والسبعين في الفترة من 14 أغسطس 2022 إلى 10 سبتمبر 2022 هي 1377. يعني ذلك أنّه خلال فترة جمع البيانات هذه، كانت% 75 من تجارب المستخدمين تتضمّن مقياس LCP أقل من 1377 ملي ثانية، و% 25 من تجارب المستخدمين تتضمّن مقياس LCP أكبر من 1377 ملي ثانية.
على الرغم من أنّ المثال لا يسرد سوى 6 إدخالات للسلسلة الزمنية وفترات جمع البيانات، تقدّم الردود من واجهة برمجة التطبيقات 25 إدخالاً للسلسلة الزمنية تلقائيًا و40 إدخالاً كحد أقصى عند تحديد "collectionPeriodCount": 40 في الطلب. بما أنّ تواريخ انتهاء كل فترة من فترات جمع البيانات هذه هي أيام سبت تفصل بينها 7 أيام، يغطي ذلك 10 أشهر مع "collectionPeriodCount": 40.
في أي ردّ، سيكون طول السلسلة الزمنية لكثافات حاويات المدرّج التكراري وقيم p75 هو نفسه تمامًا طول المصفوفة في الحقل collectionPeriods: هناك تطابق واحد إلى واحد استنادًا إلى الفهرس في هذه المصفوفات.
طلب بيانات على مستوى الصفحة
بالإضافة إلى البيانات على مستوى المصدر، تتيح CrUX History API إمكانية الوصول إلى البيانات السابقة على مستوى الصفحة. في السابق، كانت البيانات على مستوى المصدر متاحة باستخدام مجموعة بيانات CrUX على BigQuery، ولكن لم تكن البيانات السابقة على مستوى الصفحة متاحة إلا إذا جمعت المواقع الإلكترونية البيانات وخزّنتها بنفسها. تتيح واجهة برمجة التطبيقات الجديدة الآن الوصول إلى هذه البيانات السابقة على مستوى الصفحة.
يمكن طلب بيانات على مستوى الصفحة بالطريقة نفسها، ولكن باستخدام url بدلاً من origin في الحمولة:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
تخضع البيانات السابقة على مستوى الصفحة (ومستوى المصدر) لمتطلبات الأهلية نفسها التي تخضع لها بقية بيانات CrUX، وبالتالي قد لا تتضمّن الصفحات على وجه الخصوص سجلاً كاملاً للبيانات السابقة. في هذه الحالات، سيتم تمثيل البيانات "المفقودة" بالرمز "NaN" لكثافات histogramTimeseries والرمز null لـ percentilesTimeseries. سبب الاختلاف هو أنّ كثافات المدرّج التكراري تكون دائمًا أرقامًا، بينما يمكن أن تكون النسب المئوية أرقامًا أو سلاسل (يستخدم CLS السلاسل، حتى لو بدت كأرقام).
تمثيل البيانات بيانيًا
أسهل طريقة لتصوّر البيانات هي من خلال CrUX Vis، وهي أداة تم إنشاؤها خصيصًا لتوضيح فعالية CrUX History API. يمكنك الاطّلاع على مزيد من المعلومات في مستندات CrUX Vis.
لإنشاء رسومات بيانية مشابهة بنفسك، أنشأنا مثالاً على Colab. تتيح لك خدمة Colab أو Colaboratory كتابة الرموز بلغة Python وتنفيذها من داخل المتصفِّح. يستخدم CrUX History API Colab (المصدر) لغة Python لإجراء طلبات إلى واجهة برمجة التطبيقات ورسم البيانات.
يتيح لك هذا المستند في Colab إنشاء رسومات بيانية p75 ورسومات بيانية ثلاثية الخانات، والحصول على البيانات في شكل جدولي، والاطّلاع على طلبات ونتائج واجهة برمجة التطبيقات CrUX من خلال ملء نموذج موجز. لا تحتاج إلى أن تكون مبرمجًا لاستخدام هذه الأداة، ولكن يمكنك بالتأكيد الاطّلاع على رمز Python وتعديله لإنشاء شيء مذهل. نأمل أن تستمتعوا بهذه الميزة وندعوكم إلى مشاركة ملاحظاتكم بشأن ما تجدونه.
بالطبع، لا يقتصر الأمر على Colab أو Python، وهذا مجرد مثال واحد على كيفية استخدام واجهة برمجة التطبيقات الجديدة هذه. بما أنّ واجهة برمجة التطبيقات هي نقطة نهاية HTTP تستند إلى JSON، يمكن طلب البيانات منها باستخدام أي تكنولوجيا.
الخاتمة
قبل إطلاق نقطة نهاية CrUX History API، كانت المعلومات السابقة التي يمكن لمالكي المواقع الإلكترونية الحصول عليها من CrUX محدودة. كانت البيانات الشهرية على مستوى المصدر متاحة باستخدام BigQuery، ولكن لم تكن البيانات الأسبوعية متاحة، كما لم تكن البيانات السابقة على مستوى الصفحة متاحة. يمكن لمالكي المواقع الإلكترونية تسجيل هذه البيانات بأنفسهم باستخدام واجهة برمجة التطبيقات اليومية، ولكن غالبًا ما يتم اكتشاف الحاجة إلى ذلك بعد حدوث انخفاض في المقاييس.
نأمل أن تتيح واجهة برمجة التطبيقات هذه لمالكي المواقع الإلكترونية فهمًا أفضل لمقاييس مواقعهم الإلكترونية المتغيرة، وأن تكون أداة تشخيصية عند حدوث مشاكل. إذا كنت تستخدم واجهة برمجة التطبيقات الجديدة، نرحّب بتلقّي ملاحظاتك في مجموعة Google Chrome UX Report (المناقشات).
الإقرارات
الصورة الرئيسية من ديف هيرينغ على Unsplash