كيفية استخدام 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 الجديد.

تم إنشاء واجهة برمجة التطبيقات هذه بهدف تزويد المطوّرين بإمكانية وصول بسيطة وسريعة وشاملة إلى بيانات تقرير تجربة المستخدم على Chrome. لا تُبلغ واجهة برمجة التطبيقات 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 يحتوي على metrics تمثِّل توزيع تجارب المستخدمين. مقاييس التوزيع هي سلال المدرّجات التكرارية والشرائح المئوية.

{
  "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/ يحصل على تجارب "سرعة عرض أكبر جزء من المحتوى على الصفحة" (LCP) بنسبة %85 ونسبة مئوية تبلغ 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 في مستندات تقرير تجربة المستخدم على Chrome.

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

يمكن أن تختلف تجارب المستخدمين بشكلٍ كبير استنادًا إلى تحسينات الموقع الإلكتروني وظروف الشبكة وأجهزة المستخدمين. لفهم هذه الاختلافات بشكل أفضل، يمكنك التوغّل في أداء المصدر وعنوان 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}).`)
  });
}

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

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

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

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

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

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