يوفّر هذا الدليل نقطة نهاية واجهة برمجة التطبيقات لسجلّ تجربة المستخدم على Chrome (CrUX) التي توفّر سلسلة زمنية لبيانات أداء الويب. يتم تحديث هذه البيانات أسبوعيًا، وتتيح لك الاطّلاع على سجلّ يمتدّ على 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: قيمة LCP p75 للفترة من 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 ضمن رسم بياني واحد. يعطي مخطط tri-bin فكرة عن توزيع قيم المقياس التي تم قياسها خلال كل فترة جمع.
على سبيل المثال، مع أنّ الرسم البياني p75 يشير إلى أنّ قيمة INP في الموقع الإلكتروني https://web.dev كانت مقبولة تقريبًا خلال فترة الملاحظة، يُظهر الرسم البياني tri-bin أنّ مقياس INP كان ضعيفًا في الواقع بالنسبة إلى جزء صغير من عمليات تحميل الصفحات. في كلا الرسمَين البيانيَين، من السهل نسبيًا استنتاج أنّه حدث تراجع في الأداء بدأ في أواخر تشرين الأول (أكتوبر) وتم إصلاحه بحلول منتصف تشرين الثاني (نوفمبر).
لإنشاء مثل هذه الرسوم البيانية بنفسك، أنشأنا مثالاً على Colab. تتيح لك خدمة Colab أو Colaboratory كتابة الرموز بلغة Python وتنفيذها من داخل المتصفّح. يستخدم CrUX History API Colab (source) لغة Python لإجراء طلبات إلى واجهة برمجة التطبيقات وإنشاء الرسوم البيانية للبيانات.
تتيح لك خدمة Colab إنشاء رسومات بيانية من نوع p75 ورسوم بيانية ثلاثية الصناديق والحصول على البيانات في شكل جدولي والاطّلاع على زوج الطلبات والاستجابة لواجهة برمجة التطبيقات CrUX API من خلال ملء نموذج مختصر. ولا يلزم أن تكون مبرمجًا لتتمكن من استخدام هذه الرموز، ولكن يمكنك بالتأكيد إلقاء نظرة على رمز بايثون وتعديله ليكون بمثابة شيء مذهل! نتمنّى لك تجربة ممتعة، ولا تتردد في تقديم ملاحظاتك حول ما تجده.
بالطبع، لا تقتصر على استخدام Colab أو Python، وهذا مجرد مثال واحد على كيفية استخدام واجهة برمجة التطبيقات الجديدة هذه. ويمكن استخدام أي تقنية لطلب بيانات من واجهة برمجة التطبيقات باعتبارها نقطة نهاية HTTP مستندة إلى JSON.
الخاتمة
قبل طرح نقطة نهاية واجهة برمجة التطبيقات CrUX History API، كان بإمكان مالكي المواقع الإلكترونية الحصول على معلومات محدودة من CrUX. كانت البيانات الشهرية على مستوى المصدر متاحة باستخدام BigQuery ولوحة بيانات CrUX، لكن لم تكن البيانات الأسبوعية متاحة ولم تكن البيانات السابقة على مستوى الصفحة متاحة. ويستطيع مالكو المواقع الإلكترونية تسجيل هذه البيانات بأنفسهم باستخدام واجهة برمجة التطبيقات اليومية، إلا أنّه لم يتم اكتشاف الحاجة إلى ذلك في أغلب الأحيان إلا بعد تراجع المقاييس.
نأمل أن يؤدي طرح واجهة برمجة التطبيقات هذه إلى مساعدة مالكي المواقع الإلكترونية في فهم مقاييس مواقعهم الإلكترونية المتغيّرة بشكل أفضل، واستخدامها كأداة تشخيص عند ظهور مشاكل. إذا كنت تستخدِم واجهة برمجة التطبيقات الجديدة، نرحّب بملاحظاتك في مجموعة مستخدمي Chrome UX Report (Discussions) على Google.
الشكر والتقدير
الصورة الرئيسية لأحد مستخدمي Unsplash، وهو Dave Herring