يقدّم هذا الدليل نقطة نهاية واجهة برمجة التطبيقات لسجلّ تجربة المستخدم في Chrome (CrUX) التي توفّر سلسلة زمنية من بيانات أداء الويب. ويتم تعديل هذه البيانات أسبوعيًا، وتتيح لك الاطّلاع على سجلّ يعرض مدة 6 أشهر تقريبًا، مع توزيع 25 نقطة بيانات كل أسبوع.
عند استخدام هذه البيانات مع التعديلات اليومية من نقطة النهاية الأصلية لواجهة CrUX API، يمكنك الآن الاطّلاع بسرعة على أحدث البيانات وما حدث سابقًا، ما يجعلها أداة فعّالة للاطّلاع على التغييرات في صفحات الويب بمرور الوقت.
إرسال طلب إلى واجهة برمجة تطبيقات CrUX API اليومية
للتلخيص من مقالة سابقة عن واجهة برمجة تطبيقات 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 نفسه المستخدَم في المكالمة السابقة.
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"}'
الشكل العام للرد متشابه - ولكن هناك الكثير من البيانات! وبدلاً من نقطة بيانات واحدة، توجد الآن سلسلة زمنية للحقول التي تحتوي على قيم الشريحة المئوية الخامسة والسبعين (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 ملي ثانية و4020 ملي ثانية، وكانت قيمها أكبر من 4020 ملي ثانية.
وبالمثل، تتوفّر سلسلة زمنية للقيم p75: قيمة LCP p75 التي تمت في 14 آب (أغسطس) 2022 حتى 10 أيلول (سبتمبر) 2022 هي 1377. وهذا يعني أنّه خلال فترة جمع البيانات هذه، سجّلت% 75 من تجارب المستخدمين قيمة LCP أقل من 1377 ملي ثانية، وزادت قيمة LCP في 25% من تجارب المستخدمين عن 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. ويرجع سبب الاختلاف إلى أنّ كثافات المدرج التكراري هي دائمًا أرقام، في حين يمكن أن تكون الشرائح المئوية أرقامًا أو سلاسل (يستخدم متغيّرات التصميم التراكمية سلاسل، حتى إذا كانت تشبه أرقامًا).
تصور البيانات
لذلك، قد تسأل، لماذا تتشكل البيانات بهذه الطريقة؟ وقد وجد أن هذا يجعل من السهل رسم الرسوم البيانية. على سبيل المثال، إليك رسم بياني لقيم p75 لـ مدى استجابة الصفحة لتفاعلات المستخدم (INP) للموقع الإلكتروني https://web.dev:
في هذا الرسم البياني الخطي، تكون كل قيمة على المحور y هي قيمة p75 من السلسلة الزمنية p75s، والمحور x هو الوقت الذي تم إعداده على أنّه lastDate لكل فترة جمع.
فيما يلي رسم بياني للسلسلة الزمنية لسلال المدرجات التكرارية - المعروفة باسم مخطط tri-bin - لأن هذه المدرّجات التكرارية تحتوي على ثلاث سلال.
يتم إعداد المحور س ليكون lastDate لكل فترة جمع. مع ذلك، هذه المرة، المحور ص هو النسبة المئوية لعمليات تحميل الصفحات التي تقع في نطاق معين لمقياس INP، الموضح من خلال مخطط شريطي مكدس. يوفّر الرسم البياني p75 نظرة عامة سريعة، وضمن رسم بياني واحد، من السهل نسبيًا إضافة مقاييس متعددة أو عرض خطوط لكل من PHONE وDESKTOP. يتيح الرسم البياني ثلاثي السلال إمكانية توزيع القيم المترية المحسوبة خلال كل فترة جمع.
على سبيل المثال، على الرغم من أنّ الرسم البياني p75 يشير إلى أنّ https://web.dev كان يحتوي على قيم INP مقبولة تقريبًا خلال فترة الملاحظة، يُظهر الرسم البياني tri-bin أنّه على جزء صغير من عمليات تحميل الصفحات، كان مقياس INP ضعيفًا. في كلا الرسمَين البيانيين، من السهل نسبيًا استنتاج أنّ هناك تراجعًا في الأداء بدأ في نهاية تشرين الأول (أكتوبر)، وتم إصلاحه بحلول منتصف شهر تشرين الثاني (نوفمبر).
لإنشاء مثل هذه الرسوم البيانية بنفسك، أنشأنا مثالاً على Colab. يتيح لك Colab أو Colaboratory كتابة النص البرمجي Python وتنفيذه من داخل المتصفّح. يستخدم CrUX History API Colab (المصدر) لغة Python لإجراء اتصالات بواجهة برمجة التطبيقات وتخطيط البيانات.
يتيح لك Colab هذا إنشاء مخططات p75، ومخططات ثلاثية السلال، والحصول على البيانات على شكل جدول، والاطّلاع على زوج الطلبات والاستجابة لواجهة برمجة تطبيقات CrUX API، عن طريق ملء نموذج موجز. لا تحتاج إلى أن تكون مبرمجًا لاستخدام هذا، ولكن يمكنك بالتأكيد إلقاء نظرة على التعليمات البرمجية لـ Python وتعديلها لتصبح شيئًا رائعًا! نتمنى لك قضاء وقت ممتع ولا تتردد في تقديم ملاحظاتك حول ما تجده!
وبالطبع، أنت لا تقتصر على Colab أو Python وهذا مجرد مثال واحد على كيفية استخدام واجهة برمجة التطبيقات الجديدة هذه. نقطة نهاية HTTP مستندة إلى JSON، يمكن طلب البحث من واجهة برمجة التطبيقات من أي تقنية.
الخلاصة
قبل طرح نقطة نهاية واجهة برمجة التطبيقات CrUX History API، كان بإمكان مالكي المواقع الإلكترونية الحدّ من المعلومات السابقة التي يمكنهم الحصول عليها من التقرير. كانت البيانات الشهرية على مستوى المصدر متاحة باستخدام BigQuery ولوحة بيانات CrUX، ولكن لم تكن البيانات الأسبوعية متاحة ولم تكن البيانات السابقة على مستوى الصفحة. ويمكن لمالكي المواقع الإلكترونية تسجيل هذه البيانات بأنفسهم باستخدام واجهة برمجة التطبيقات اليومية، ولكن غالبًا ما لم يتم اكتشاف الحاجة إلى ذلك إلا بعد تراجع المقاييس.
نحن نأمل مع طرح واجهة برمجة التطبيقات CrUX History API أن يسمح لمالكي المواقع الإلكترونية بفهم أفضل لمقاييس مواقعهم المتغيّرة، وأداة تشخيص عند ظهور مشاكل. إذا كنت تستخدم واجهة برمجة التطبيقات الجديدة، نرحّب بالملاحظات والآراء في مجموعة Google الخاصة بتقارير تجربة المستخدم (المناقشات) على Chrome.
شكر وتقدير
صورة رئيسية من تصوير ديف هيرينغ على UnLaunch