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

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

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

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

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

لنطّلع على كيفية استخدامها.

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

جرِّبه الآن

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

تشمل مصادر البيانات في مجموعة بيانات CrUX جميع التجارب الأساسية على مستوى الصفحة. يوضّح المثال التالي كيفية طلب بيانات تجربة المستخدِم لمصدر معيّن من واجهة برمجة التطبيقات CrUX باستخدام 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، وأنّ القيمة التي تم احتسابها عند بلوغ نسبة %75 هي 1,947 ملي ثانية، وهي أفضل قليلاً من التوزيع على مستوى المصدر.

توحيد عناوين URL

قد تعمل واجهة برمجة التطبيقات CrUX API على توحيد عناوين 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}).`)
  });
}

تُظهر النتائج أنّ هذه الصفحة تجتاز تقييمات "مؤشرات أداء الويب الأساسية" لجميع المقاييس الثلاثة.

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 لضمان تحسين سرعة تجارب المستخدمين الفعليين والحفاظ على هذه السرعة. لمزيد من المعلومات عن "مؤشرات أداء الويب الأساسية" وكيفية قياسها، اطّلِع على مؤشرات أداء الويب وأدوات قياس "مؤشرات أداء الويب الأساسية".

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

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

  • المقاييس الإضافية
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • السمات الإضافية
    • month
    • country
    • effective connection type (توقيت شرق أوروبا)
  • دقة إضافية
    • المخطّطات البيانية للمدرّجات التكرارية المفصّلة
    • المزيد من المعدّلات المئوية

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