يقدّم هذا الدليل نقطة نهاية Chrome UX Report (CrUX) History API التي تقدّم سلسلة زمنية لبيانات أداء الويب. يتم تحديث هذه البيانات أسبوعيًا، وتتيح لك الاطّلاع على سجلّ يمتدّ على 6 أشهر تقريبًا، مع 25 نقطة بيانات متباعدة كل أسبوع.
عند استخدامها مع التعديلات اليومية من نقطة نهاية 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_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"}'
يتشابه الشكل العام للردّ، ولكن هناك الكثير من البيانات الإضافية. بدلاً من نقطة بيانات واحدة، تتوفّر الآن سلاسل زمنية للحقول التي تحتوي على الشريحة المئوية الـ 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 إدخالًا للسلسلة الزمنية، وبما أنّ تواريخ الانتهاء لكل فترة من فترات جمع البيانات هي أيام السبت التي تفصل بينها 7 أيام، فإنّ ذلك يشمل 6 أشهر.
في أيّ استجابة معيّنة، سيكون طول السلسلة الزمنية لكثافة أقسام الرسم البياني الشريطي وقيم 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 سلاسل، حتى لو كانت تبدو مثل الأرقام).
عرض البيانات بيانيًا
قد تتساءل، لماذا يتم تشكيل البيانات بهذه الطريقة؟ تبيّن أنّ ذلك يسهّل رسم الرسوم البيانية. على سبيل المثال، في ما يلي رسم بياني لقيم p75 لمقياس مدى استجابة الصفحة لتفاعلات المستخدم (INP) لموقع https://web.dev الإلكتروني:
في هذا الرسم البياني الخطي، كل قيمة على محور الصعود والهبوط هي قيمة p75 من السلسلة الزمنية p75s، والمحور السيني هو الوقت الذي تم إعداده على أنّه lastDate لكل فترة جمع.
في ما يلي رسم بياني للسلسلة الزمنية لسلة المدرج التكراري، والمعروفة باسم مخطّط السلال الثلاثية، لأنّ هذه المخططات التكرارية تحتوي على ثلاث سلال.
يتم إعداد محور x على أنّه lastDate لكل فترة جمع. في هذه المرة، يمثّل محور السينات النسبة المئوية لعمليات تحميل الصفحات التي تندرج ضمن نطاق معيّن لمقياس INP، ويتم عرضها من خلال رسم بياني شريطي مجمّع. يوفّر الرسم البياني لقيمة p75 نظرة عامة سريعة، ومن السهل نسبيًا إضافة مقاييس متعددة أو عرض خطوط لكل من PHONE وDESKTOP ضمن رسم بياني واحد. يقدّم الرسم البياني الثلاثي الحزم فكرة عن توزيع قيم المقاييس التي تم قياسها خلال كل فترة جمع.
على سبيل المثال، على الرغم من أنّ الرسم البياني لقيمة p75 يشير إلى أنّ https://web.dev كانت قيم INP مقبولة تقريبًا خلال فترة المراقبة، يُظهر الرسم البياني الثلاثي الأقسام أنّ قيمة INP كانت سيئة في الواقع بالنسبة إلى جزء صغير من عمليات تحميل الصفحات. في كلا الرسمَين البيانيَين، من السهل نسبيًا استنتاج أنّه حدث تراجع في الأداء بدأ في أواخر تشرين الأول (أكتوبر) وتم إصلاحه بحلول منتصف تشرين الثاني (نوفمبر).
لإنشاء مثل هذه الرسوم البيانية بنفسك، أنشأنا مثالاً على 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 (Discussions) على Google.
الشكر والتقدير
الصورة الرئيسية لأحد مستخدمي Unsplash، وهو Dave Herring