كيفية استخدام CrUX History API

Johannes Henkel

Jasmine Yan

Barry Pollard

يوفّر هذا الدليل نقطة نهاية واجهة برمجة التطبيقات لسجلّ تجربة المستخدم على 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_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، كانت قيم LCP لنسبة %91.87 من عمليات تحميل الصفحات أصغر من 2500 ملي ثانية، وكانت القيم بنسبة %5.27 بين 2500 و%2000 ملي ثانية أكبر من 2500 و%2008 ملي ثانية.

وبالمثل، هناك سلسلة زمنية للقيم p75: قيمة LCP p75 للفترة من 14 آب (أغسطس) 2022 حتى 10 أيلول (سبتمبر) 2022 كانت 1377. وهذا يعني أنّه خلال فترة جمع البيانات هذه، كان سرعة عرض أكبر جزء من المحتوى على الصفحة (LCP) أقل من 1377 ملي ثانية في% 75 من تجارب المستخدمين، وكان لـ% 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/"}'

تخضع البيانات السابقة على مستوى الصفحة (وعلى مستوى المصدر) لمتطلبات الأهلية نفسها مثل بقية تقارير تجربة المستخدم على Chrome، وبالتالي قد لا تحتوي الصفحات على وجه التحديد على سجلّ سجلّ كامل. في هذه الحالات، "مفقود" سيتم تمثيل البيانات بواسطة "NaN" لكثافات histogramTimeseries وnull في percentilesTimeseries. وسبب الاختلاف هو أن كثافات المدرج التكراري تكون دائمًا أرقامًا، بينما يمكن أن تكون القيم المئوية أرقامًا أو سلاسل (تستخدم متغيّرات التصميم التراكمية (CLS) السلاسل، حتى إذا كانت تبدو كأرقام).

تصور البيانات

لذا، قد تسأل، لماذا يتم تشكيل البيانات بهذه الطريقة؟ وقد وجد أن هذا يسهل رسم الرسوم البيانية. على سبيل المثال، في ما يلي رسم بياني لقيم p75 لـ مدى استجابة الصفحة لتفاعلات المستخدم (INP) لـ https://web.dev:

في هذا الرسم البياني الخطي، تكون كل قيمة على المحور الصادي هي قيمة p75 من السلسلة الزمنية p75s، والمحور س هو الوقت الذي يتم إعداده على أنّه lastDate لكل فترة جمع.

فيما يلي رسم بياني للسلسلة الزمنية لسلة المدرّج التكراري - والمعروفة باسم مخطط ثلاثي السلة - لأن هذه المدرجات التكرارية تحتوي على ثلاث سلال.

يتم إعداد المحور "س" باعتباره lastDate لكل فترة جمع. في هذه المرة، المحور الصادي هو النسبة المئوية لعمليات تحميل الصفحات التي تقع في نطاق معيّن لمقياس INP، ويظهر في رسم بياني شريطي مكدّس. يوفّر الرسم البياني p75 نظرة عامة سريعة، ومن السهل نسبيًا إضافة مقاييس متعدّدة أو عرض أسطر لكلٍّ من PHONE وDESKTOP ضمن رسم بياني واحد. يعطي مخطط tri-bin فكرة عن توزيع قيم المقياس التي تم قياسها خلال كل فترة جمع.

على سبيل المثال، مع أنّ الرسم البياني p75 يشير إلى أنّ قيمة INP في الموقع الإلكتروني https://web.dev كانت مقبولة تقريبًا خلال فترة الملاحظة، يُظهر الرسم البياني tri-bin أنّ مقياس INP كان ضعيفًا في الواقع بالنسبة إلى جزء صغير من عمليات تحميل الصفحات. في كلا الرسمين البيانيين، من السهل نسبيًا استنتاج أنّ هناك تراجعًا في الأداء بدأ في نهاية شهر تشرين الأول (أكتوبر)، وتم إصلاحه بحلول منتصف شهر تشرين الثاني (نوفمبر).

لإنشاء هذه الرسوم البيانية بنفسك، أنشأنا مثالاً على Colab. تتيح لك Colab أو Colaboratory كتابة الرموز بلغة Python وتنفيذها من داخل المتصفِّح. تستخدم CrUX History API على Colab (المصدر) لغة Python لإجراء طلبات على واجهة برمجة التطبيقات وتخطيط البيانات.

تتيح لك خدمة Colab إنشاء رسومات بيانية من نوع p75 ورسوم بيانية ثلاثية الصناديق والحصول على البيانات في شكل جدولي والاطّلاع على زوج الطلبات والاستجابة لواجهة برمجة التطبيقات CrUX API من خلال ملء نموذج مختصر. ولا يلزم أن تكون مبرمجًا لتتمكن من استخدام هذه الرموز، ولكن يمكنك بالتأكيد إلقاء نظرة على رمز بايثون وتعديله ليكون بمثابة شيء مذهل! نتمنّى لك تجربة ممتعة ولا تتردد في تقديم ملاحظاتك حول ما تعثر عليه.

بالطبع، لا يقتصر الأمر على Colab أو Python، وهذا مثال واحد على كيفية استخدام واجهة برمجة التطبيقات الجديدة هذه. يمكن استخدام أي تقنية لطلب بحث واجهة برمجة التطبيقات، وهي نقطة نهاية HTTP مستندة إلى JSON.

الخاتمة

قبل إطلاق نقطة نهاية واجهة برمجة التطبيقات CrUX History API، كان بإمكان مالكي المواقع الإلكترونية الحصول على معلومات سابقة محدودة من خلال تقرير تجربة المستخدم على Chrome. كانت البيانات الشهرية على مستوى المصدر متاحة باستخدام BigQuery ولوحة بيانات CrUX، لكن لم تكن البيانات الأسبوعية متاحة ولم تكن البيانات السابقة على مستوى الصفحة متاحة. ويمكن لمالكي المواقع الإلكترونية تسجيل هذه البيانات بأنفسهم باستخدام واجهة برمجة التطبيقات اليومية، إلا أنّ الحاجة إلى ذلك لم يتم اكتشافها إلا في أغلب الأحيان بعد تراجع المقاييس.

نأمل من خلال طرح واجهة CrUX History API هذه أن تتيح لمالكي المواقع الإلكترونية التعرّف بشكل أفضل على المقاييس المتغيّرة لمواقعهم الإلكترونية، وكأداة تشخيصية عند ظهور مشاكل. إذا كنت تستخدم واجهة برمجة التطبيقات الجديدة، نحن نرحّب بالملاحظات والآراء في مجموعة Google لتقرير تجربة المستخدم في Chrome (المناقشات).

شكر وتقدير

صورة رئيسية من تصميم "ديف هيرينغ" على إلغاء البداية