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

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

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

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

لضمان وصول المطوّرين إلى جميع المقاييس الأكثر أهمية، وهي مؤشرات أداء الويب الأساسية، تعمل واجهة CrUX API على تدقيق ومراقبة سرعة عرض أكبر محتوى مرئي (LCP) ومهلة الاستجابة الأولى (FID) ومتغيّرات التصميم التراكمية (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 ملّي ثانية، وهو ما يُعدّ "جيدًا". الحدّ الأدنى لسرعة عرض أكبر محتوى مرئي. وتعني القيمة 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 في 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) تبلغ 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 لتقييم ما إذا كان توزيع مقاييس "مؤشرات أداء الويب الأساسية" (LCP وFID وCLS) في صفحة ويب "جيدًا".

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

function assessCoreWebVitals(response) {
  // See https://web.dev/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'first_input_delay',
    '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 first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

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

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

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

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

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