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

تعرَّف على كيفية استخدام Chrome UX Report API للوصول إلى بيانات تجربة المستخدم الحقيقية على ملايين المواقع الإلكترونية.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

تمثّل مجموعة بيانات تقرير تجربة المستخدم في Chrome (أو CrUX) تجربة مستخدمي Chrome الفعليين في الوجهات الرائجة على الويب. منذ عام 2017، عندما تم إطلاق مجموعة البيانات القابلة للبحث لأول مرة على BigQuery، تم دمج البيانات الفعلية من CrUX في أدوات المطوّرين، مثل إحصاءات PageSpeed وتقرير Core Web Vitals في Search Console، ما يتيح للمطوّرين قياس تجارب المستخدمين الفعليين وتتبُّعها. كانت الأداة التي توفّر وصولاً مجانيًا ومتوافقًا مع REST إلى بيانات CrUX بطريقة آلية هي الجزء الناقص طوال هذه المدة. للمساعدة في سدّ هذه الفجوة، يسرّنا الإعلان عن إطلاق Chrome UX Report API الجديدة كليًا.

تم إنشاء واجهة برمجة التطبيقات هذه بهدف تزويد المطوّرين بإمكانية الوصول السريع والشامل إلى بيانات CrUX. لا تعرض CrUX API سوى بيانات تجربة المستخدم الفعلية، على عكس PageSpeed Insights API الحالية التي تعرض أيضًا بيانات المختبر من عمليات تدقيق الأداء في Lighthouse. تم تبسيط واجهة برمجة التطبيقات CrUX API ويمكنها عرض بيانات تجربة المستخدم بسرعة، ما يجعلها مناسبة تمامًا لتطبيقات التدقيق في الوقت الفعلي.

لضمان وصول المطوّرين إلى جميع المقاييس الأكثر أهمية، أي مؤشرات Core Web Vitals، تعمل واجهة برمجة التطبيقات CrUX على تدقيق ومراقبة سرعة عرض أكبر محتوى مرئي (LCP) ومدى استجابة الصفحة لتفاعلات المستخدم (INP) ومتغيّرات التصميم التراكمية (CLS) على مستوى المصدر وعنوان URL.

لنبدأ ونرى كيفية استخدامه.

تجربة واجهة برمجة التطبيقات على هذه الصفحة

جرِّبه الآن

بيانات مصدر طلب البحث

تشمل المصادر في مجموعة بيانات CrUX جميع التجارب الأساسية على مستوى الصفحة. يوضّح المثال التالي كيفية طلب بيانات تجربة المستخدم الخاصة بمصدر معيّن من خلال واجهة برمجة التطبيقات CrUX API باستخدام curl في سطر الأوامر.

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"}'

يتكوّن الأمر curl من ثلاثة أجزاء:

  1. نقطة نهاية عنوان URL الخاصة بواجهة برمجة التطبيقات، بما في ذلك مفتاح واجهة برمجة التطبيقات الخاص بالمُتصل
  2. العنوان Content-Type: application/json، الذي يشير إلى أنّ نص الطلب يحتوي على JSON
  3. نص الطلب بترميز JSON، والذي يحدّد مصدر https://web.dev.

لتنفيذ الإجراء نفسه في JavaScript، استخدِم الأداة المساعدة CrUXApiUtil، التي تنفّذ طلب البيانات من واجهة برمجة التطبيقات وتعرض الردّ الذي تم فك ترميزه (يمكنك أيضًا الاطّلاع على نسخة Github الخاصة بنا للحصول على المزيد من الميزات، بما في ذلك السجلّ وإمكانية معالجة الدفعات).

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

استبدِل [YOUR_API_KEY] بمفتاحك. بعد ذلك، استدعِ الدالة CrUXApiUtil.query وأدخِل عنصر نص الطلب.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

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

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            "density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

تمثّل السمتان start وend للعنصر histogram نطاق القيم التي يواجهها المستخدمون للمقياس المحدّد. تمثّل السمة density نسبة تجارب المستخدمين ضمن هذا النطاق. في هذا المثال، %79 من تجارب المستخدمين التي تتضمّن مقياس LCP على جميع صفحات web.dev تقلّ عن 2,500 ملّي ثانية، وهو الحدّ الأدنى الجيد لمقياس LCP. تعني القيمة percentiles.p75 أنّ% 75 من تجارب المستخدمين في هذا التوزيع تقلّ عن 2,216 ملي ثانية. يمكنك الاطّلاع على مزيد من المعلومات حول بنية الرد في مستندات نص الرد.

الأخطاء

عندما لا تتوفّر أي بيانات في CrUX API لمصدر معيّن، يستجيب برسالة خطأ بترميز JSON:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

لتصحيح هذا الخطأ، تحقَّق أولاً من إمكانية الانتقال إلى المصدر المطلوب بشكل علني. يمكنك اختبار ذلك عن طريق إدخال المصدر في شريط العناوين في المتصفّح ومقارنته بعنوان URL النهائي بعد أي عمليات إعادة توجيه. تشمل المشاكل الشائعة إضافة النطاق الفرعي أو حذفه بدون داعٍ واستخدام بروتوكول HTTP غير صحيح.

خطأ
{"origin": "http://www.web.dev"}

يتضمّن هذا المصدر بشكل غير صحيح البروتوكول http:// والنطاق الفرعي www..

تم الإجراء بنجاح
{"origin": "https://web.dev"}

يمكن للجميع الوصول إلى هذا المصدر.

إذا كان المصدر المطلوب هو الإصدار القابل للتصفّح، قد يحدث هذا الخطأ أيضًا إذا كان المصدر يتضمّن عددًا غير كافٍ من العيّنات. يجب أن تتضمّن جميع المصادر وعناوين URL المُدرَجة في مجموعة البيانات عددًا كافيًا من العيّنات لإخفاء هوية المستخدمين الفرديين. بالإضافة إلى ذلك، يجب أن تكون المصادر وعناوين URL قابلة للفهرسة بشكل علني. راجِع منهجية CrUX لمعرفة المزيد حول كيفية تضمين المواقع الإلكترونية في مجموعة البيانات.

بيانات عنوان URL الخاص بطلب البحث

لقد تعرّفت على كيفية طلب بيانات من CrUX API بشأن تجربة المستخدم الإجمالية على مصدر معيّن. لحصر النتائج على صفحة معيّنة، استخدِم مَعلمة الطلب url.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

يشبه أمر curl هذا مثال المصدر، باستثناء أنّ نص الطلب يستخدم المَعلمة url لتحديد الصفحة التي سيتم البحث عنها.

لطلب بيانات عناوين URL من CrUX API باستخدام JavaScript، استدعِ الدالة CrUXApiUtil.query باستخدام المَعلمة url في نص الطلب.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

إذا كانت بيانات عنوان URL هذا متوفرة في مجموعة بيانات CrUX، ستعرض واجهة برمجة التطبيقات استجابة بترميز JSON. على سبيل المثال:

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

وكما هو متوقّع، تُظهر النتائج أنّ https://web.dev/fast/ حقّق %85 من تجارب LCP "الجيدة"، وبلغت قيمة مقياس LCP في الشريحة المئوية الخامسة والسبعين 1,947 ملي ثانية، ما يُعدّ أفضل قليلاً من التوزيع على مستوى المصدر.

تسوية عناوين URL

قد تعمل واجهة برمجة التطبيقات الخاصة بـ "تقرير تجربة المستخدم على Chrome" على تسوية عناوين URL المطلوبة لتتطابق بشكل أفضل مع قائمة عناوين URL المعروفة. على سبيل المثال، سيؤدي طلب البحث عن عنوان URL https://web.dev/fast/#measure-performance-in-the-field إلى عرض بيانات https://web.dev/fast/ بسبب التسوية. في هذه الحالة، سيتم تضمين عنصر urlNormalizationDetails في الردّ.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

يمكنك الاطّلاع على مزيد من المعلومات حول تسوية عناوين URL في مستندات CrUX.

طلب البحث حسب شكل الجهاز

يمكن أن تختلف تجارب المستخدمين بشكل كبير حسب تحسينات الموقع الإلكتروني وظروف الشبكة وأجهزة المستخدمين. لفهم هذه الاختلافات بشكل أفضل، يمكنك الانتقال إلى تفاصيل أداء المصدر وعنوان URL باستخدام السمة formFactor في CrUX API.

تتيح واجهة برمجة التطبيقات ثلاث قيم صريحة لعامل الشكل: DESKTOP وPHONE وTABLET. بالإضافة إلى المصدر أو عنوان URL، حدِّد إحدى القيم التالية في نص الطلب لحصر النتائج في تجارب المستخدمين هذه فقط. يوضّح هذا المثال كيفية طلب البيانات من واجهة برمجة التطبيقات حسب شكل الجهاز باستخدام curl.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

لطلب بيانات خاصة بعامل الشكل من CrUX API باستخدام JavaScript، استدعِ الدالة CrUXApiUtil.query باستخدام المَعلمتَين url وformFactor في نص الطلب.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

إنّ حذف المَعلمة formFactor يعادل طلب بيانات لجميع أشكال الأجهزة معًا.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

سيعرض الحقل key في الردّ إعدادات الطلب formFactor للتأكّد من تضمين تجارب الهاتف فقط.

تذكَّر من القسم السابق أنّ% 85 من تجارب المستخدمين على هذه الصفحة كانت تتضمّن مقياس LCP "جيد". قارِن ذلك بالتجارب الخاصة بالهواتف، والتي يُصنّف% 78 منها فقط على أنّها "جيدة". كما أنّ الشريحة المئوية الخامسة والسبعين أبطأ أيضًا بين تجارب الهاتف، حيث ارتفعت من 1,947 مللي ثانية إلى 2,366 مللي ثانية. يمكن أن يؤدي التقسيم حسب عامل الشكل إلى إبراز التفاوتات الأكثر تطرفًا في تجارب المستخدمين.

تقييم أداء "مؤشرات أداء الويب الأساسية"

يحدّد برنامج مؤشرات أداء الويب الأساسية أهدافًا تساعد في تحديد ما إذا كان يمكن اعتبار تجربة المستخدم أو توزيع التجارب "جيدًا". في المثال التالي، نستخدم CrUX API والدالة CrUXApiUtil.query لتقييم ما إذا كان توزيع مقاييس Core Web Vitals (سرعة عرض أكبر محتوى مرئي (LCP) ومدى استجابة الصفحة لتفاعلات المستخدم (INP) ومتغيّرات التصميم التراكمية (CLS)) على صفحة ويب "جيّدًا".

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the "good" threshold.
    const passes = p75 < threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

تُظهر النتائج أنّ هذه الصفحة تجتاز تقييمات Core Web Vitals لجميع المقاييس الثلاثة.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

وباستخدام طريقة آلية لمراقبة نتائج واجهة برمجة التطبيقات، يمكن استخدام البيانات من CrUX لضمان سرعة تجارب المستخدمين الفعليين والحفاظ على هذه السرعة. لمزيد من المعلومات حول مؤشرات Core Web Vitals وكيفية قياسها، يمكنك الاطّلاع على Web Vitals وأدوات قياس مؤشرات Core Web Vitals.

ما هي الخطوات التالية؟

لا تتضمّن الميزات المضمّنة في الإصدار الأوّلي من CrUX API سوى بعض أنواع الإحصاءات التي يمكن الحصول عليها من خلال CrUX. قد يكون مستخدمو مجموعة بيانات CrUX على BigQuery على دراية ببعض الميزات الأكثر تقدّمًا، بما في ذلك:

  • مقاييس إضافية
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • سمات إضافية
    • month
    • country
  • مستوى دقة إضافي
    • المدرّجات التكرارية التفصيلية
    • المزيد من النسب المئوية

يمكنك الاطّلاع على مستندات CrUX API الرسمية للحصول على مفتاح واجهة برمجة التطبيقات واستكشاف المزيد من الأمثلة على التطبيقات. نأمل أن تجرّب هذه الميزة، ويسرّنا تلقّي أي أسئلة أو ملاحظات لديك، لذا يُرجى التواصل معنا على منتدى مناقشة CrUX. للاطّلاع على كل ما خطّطنا له بشأن CrUX API، يمكنك الاشتراك في منتدى إشعارات CrUX أو متابعتنا على Twitter على ‎@ChromeUXReport.