تاريخ النشر: 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 نفسه المستخدَم في الطلب السابق.
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 مللي ثانية.
وبالمثل، تتوفّر سلسلة زمنية لقيم p75: كانت قيمة p75 لمقياس LCP في الفترة من 14 آب (أغسطس) 2022 إلى 10 أيلول (سبتمبر) 2022 هي 1377. وهذا يعني أنّه خلال فترة جمع البيانات هذه، سجّلت نسبة% 75 من تجارب المستخدمين وقت LCP أقل من 1377 ملي ثانية، وسجّلت نسبة% 25 من تجارب المستخدمين وقت LCP أكبر من 1377 ملي ثانية.
على الرغم من أنّ المثال لا يسرد سوى 6 إدخالات للسلسلة الزمنية وفترات جمع البيانات، توفّر الردود الواردة من واجهة برمجة التطبيقات 25 إدخالًا للسلسلة الزمنية تلقائيًا و40 إدخالًا بحد أقصى عند تحديد "collectionPeriodCount": 40 في الطلب. بما أنّ تواريخ انتهاء كلّ فترة من فترات جمع البيانات هذه هي أيام السبت التي تفصل بينها 7 أيام، فإنّ "collectionPeriodCount": 40 تشمل 10 أشهر.
في أيّ استجابة معيّنة، سيكون طول السلسلة الزمنية لكثافة أقسام الرسم البياني الشريطي وقيم p75 مطابقًا تمامًا لطول الصفيف في حقل collectionPeriods: هناك تطابق واحد لواحد استنادًا إلى الفهرس في هذه الصفائف.
طلب البيانات على مستوى الصفحة
بالإضافة إلى البيانات على مستوى المصدر، تسمح واجهة برمجة التطبيقات CrUX History API بالوصول إلى البيانات السابقة على مستوى الصفحة. في حين أنّ البيانات على مستوى المصدر كانت متاحة سابقًا باستخدام مجموعة بيانات CrUX على BigQuery (أو باستخدام لوحة بيانات CrUX)، لم تكن البيانات السابقة على مستوى الصفحة متاحة إلا إذا كانت المواقع الإلكترونية تجمع البيانات وتخزّنها بنفسها. تتيح واجهة برمجة التطبيقات الجديدة الآن الوصول إلى هذه البيانات السابقة على مستوى الصفحة.
يمكن طلب البيانات على مستوى الصفحة بالطريقة نفسها، ولكن باستخدام 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 (source) لغة Python لإجراء طلبات إلى واجهة برمجة التطبيقات وإنشاء الرسوم البيانية للبيانات.
يتيح لك تطبيق Colab هذا إنشاء رسوم بيانية لقيمة p75 ورسوم بيانية ثلاثية الحزم والحصول على البيانات في شكل جدولي والاطّلاع على زوج الطلب والاستجابة لواجهة برمجة التطبيقات CrUX API، وذلك من خلال ملء نموذج موجز. لست بحاجة إلى أن تكون مبرمجًا لاستخدام هذه الميزة، ولكن يمكنك بالتأكيد الاطّلاع على رمز Python وتعديله إلى شيء رائع. نتمنّى لك تجربة ممتعة، ولا تتردد في تقديم ملاحظاتك حول ما تجده.
بالطبع، لا تقتصر على استخدام Colab أو Python، وهذا مجرد مثال واحد على كيفية استخدام واجهة برمجة التطبيقات الجديدة هذه. بصفتها نقطة نهاية HTTP مستندة إلى JSON، يمكن إجراء طلب بحث في واجهة برمجة التطبيقات من أي تقنية.
الخاتمة
قبل طرح نقطة نهاية واجهة برمجة التطبيقات CrUX History API، كان بإمكان مالكي المواقع الإلكترونية الحصول على معلومات محدودة من CrUX. كانت البيانات الشهرية على مستوى المصدر متاحة باستخدام BigQuery ولوحة بيانات CrUX، ولكن لم تكن البيانات الأسبوعية متاحة، كما لم تكن البيانات السابقة على مستوى الصفحة متاحة. يمكن لمالكي المواقع الإلكترونية تسجيل هذه البيانات بأنفسهم باستخدام واجهة برمجة التطبيقات اليومية، ولكن في أغلب الأحيان، لا يتم اكتشاف الحاجة إلى ذلك إلا بعد حدوث تراجع في المقاييس.
نأمل أن يؤدي طرح واجهة برمجة التطبيقات هذه إلى مساعدة مالكي المواقع الإلكترونية في فهم مقاييس مواقعهم الإلكترونية المتغيّرة بشكل أفضل، واستخدامها كأداة تشخيص عند حدوث مشاكل. إذا كنت تستخدِم واجهة برمجة التطبيقات الجديدة، نرحّب بملاحظاتك في مجموعة مستخدمي Chrome UX Report (Discussions) على Google.
الشكر والتقدير
الصورة الرئيسية لأحد مستخدمي Unsplash، وهو Dave Herring