واجهة برمجة تطبيقات CrUX

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

حالة الاستخدام الشائعة

تسمح واجهة برمجة تطبيقات CrUX API بطلب البحث عن مقاييس تجربة المستخدم لمعرّف موارد منتظم (URI) محدّد، مثل "الحصول على مقاييس لمصدر https://example.com".

مفتاح واجهة برمجة تطبيقات CrUX

يتطلب استخدام CrUX API مفتاح Google Cloud API. يمكنك إنشاء حساب في صفحة بيانات الاعتماد وتوفيره لاستخدام Chrome UX Report API.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق مَعلمة طلب البحث key=[YOUR_API_KEY] بجميع عناوين URL للطلبات. ويمكنك الاطّلاع على أمثلة على طلبات البحث.

يمكن تضمين مفتاح واجهة برمجة التطبيقات في عناوين URL بشكل آمن ولا يحتاج إلى أي ترميز.

نموذج البيانات

يوضح هذا القسم بالتفصيل هيكل البيانات في الطلبات والردود.

تسجيل

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

المعرّفات

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

الأصل

عندما يكون المعرّف مصدرًا، يتم تجميع كل البيانات المتوفّرة لكل الصفحات في ذلك المصدر معًا. على سبيل المثال، لنفترض أنّ أصل http://www.example.com يحتوي على صفحات كما هو موضّح في خريطة الموقع هذه:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

وهذا يعني أنّه عند إجراء طلب بحث في تقرير تجربة المستخدم من Chrome مع ضبط المصدر على http://www.example.com، سيتم عرض بيانات http://www.example.com/ وhttp://www.example.com/foo.html وhttp://www.example.com/bar.html مجمّعة معًا، لأنّ هذه هي كل الصفحات التي تندرج ضمن هذا المصدر.

عناوين URL

وعندما يكون المُعرف عنوان URL، لن يتم عرض سوى البيانات الخاصة بعنوان URL المحدّد. جارٍ البحث مرّة أخرى في خريطة الموقع المصدر الخاصة بـ http://www.example.com:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

في حال ضبط المعرّف على عنوان URL بالقيمة http://www.example.com/foo.html، لن يتمّ عرض سوى بيانات تلك الصفحة.

الأبعاد

تحدد السمات مجموعة معيّنة من البيانات التي يتم تجميع سجلّ بناءً عليها. يشير عامل الشكل PHONE مثلاً إلى أنّ السجلّ يحتوي على معلومات حول عمليات التحميل التي تمت على جهاز جوّال. ستحتوي كل سمة على عدد معيّن من القيم، وسيؤدي عدم تحديد هذه السمة ضمنيًا إلى تجميع السمة على جميع القيم. على سبيل المثال، يشير عدم تحديد أي شكل للجهاز إلى أنّ السجلّ يحتوي على معلومات حول عمليات التحميل التي حدثت في أي شكل جهاز.

عامل التكوين

فئة الجهاز التي استخدمها المستخدم النهائي للانتقال إلى الصفحة. هذه فئة عامة من الأجهزة مقسّمة إلى PHONE وTABLET وDESKTOP.

نوع الاتصال الفعّال

نوع الاتصال الفعّال هو جودة الاتصال المقدَّرة للجهاز عند الانتقال إلى الصفحة. هذا فصل عام مُقسَّم إلى offline وslow-2G و2G و3G و4G.

المقياس

ويتم تسجيل المقاييس في صورة تجميعات إحصائية في المدرّجات التكرارية والنسب المئوية والكسور.

يتم تقريب قيم النقاط العائمة إلى 4 منازل عشرية (تجدر الإشارة إلى أنّه يتم ترميز مقاييس cumulative_layout_shift مرتين كسلسلة، لذا لا يتم أخذ أعداد عشرية في الاعتبار ويتم الإبلاغ عنها في خانتَين عشريتَين داخل السلسلة).

التردد الرسومي

عندما يتم التعبير عن المقاييس في مدرّج تكراري، نعرض النسب المئوية لعمليات تحميل الصفحات التي تندرج ضمن نطاقات معيّنة لهذا المقياس.

يظهر المدرّج التكراري البسيط المكون من ثلاثة سلال لمثال مقياس على النحو التالي:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

تشير هذه البيانات إلى أنّه بالنسبة إلى% 38.18 من عمليات تحميل الصفحات، تم قياس النموذج النموذجي بين 0 ملي ثانية و1,000 ملي ثانية. لا يتم تضمين وحدات المقياس في هذا المدرج التكراري، وفي هذه الحالة سنفترض بالمللي ثانية.

بالإضافة إلى ذلك، شهدت نسبة 49.91% من عمليات تحميل الصفحات قيمة مقياس تتراوح بين 1,000 و3,000 ملي ثانية، بينما رأى 11.92% قيمة أكبر من 3,000 ملي ثانية.

الشرائح المئوية

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

{
  "percentiles": {
    "p75": 2063
  }
}

في هذا المثال، تم قياس 75% على الأقل من عمليات تحميل الصفحات باستخدام قيمة مقياس <= 2063.

الكسور

تشير الكسور إلى النسب المئوية لعمليات تحميل الصفحات التي يمكن تصنيفها بطريقة معيّنة. وفي هذه الحالة، تكون قيم المقياس هي هذه التصنيفات.

على سبيل المثال، يتكوّن مقياس form_factors من عنصر fractions يسرد تفاصيل أشكال الأجهزة (أو الأجهزة) التي يشملها طلب البحث المحدّد:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

وفي هذه الحالة، تم قياس 3.77% من عمليات تحميل الصفحات على أجهزة الكمبيوتر المكتبي، و2.88% على الأجهزة اللوحية، و93.35% على الهاتف، ما يعني أنّ إجمالي عمليات تحميل الصفحات يصل إلى 100%.

أنواع قيم المقاييس

اسم مقياس CrUX API نوع البيانات الوحدات المترية التجميعات الإحصائية الوثائق
cumulative_layout_shift تم ترميزهما بخانتَين عشريتَين كسلسلة بلا وحدة رسم بياني لثلاث سلال، شرائح مئوية مكونة من p75 cls
first_contentful_paint int مللي ثانية رسم بياني لثلاث سلال، شرائح مئوية مكونة من p75 fcp
first_input_delay
(متوقّفة نهائيًا)		 int مللي ثانية رسم بياني لثلاث سلال، شرائح مئوية مكونة من p75 حساب العميل
interaction_to_next_paint int مللي ثانية رسم بياني لثلاث سلال، شرائح مئوية مكونة من p75 inp
largest_contentful_paint int مللي ثانية رسم بياني لثلاث سلال، شرائح مئوية مكونة من p75 lcp
experimental_time_to_first_byte int مللي ثانية رسم بياني لثلاث سلال، شرائح مئوية مكونة من p75 ttfb
form_factors خانات عشرية مزدوجة النسبة المئوية التعيين من شكل الجهاز إلى الكسر أشكال الأجهزة
navigation_types خانات عشرية مزدوجة النسبة المئوية التعيين من نوع التنقل إلى الكسر أنواع التنقّل

ربط اسم مقياس BigQuery

اسم مقياس CrUX API اسم مقياس BigQuery
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
first_input_delay first_input.delay
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
navigation_types navigation_types
form_factors timing fixed in amara

فترة جمع البيانات

اعتبارًا من تشرين الأول (أكتوبر) 2022، ستتضمّن واجهة برمجة تطبيقات CrUX API عنصر collectionPeriod يحتوي على حقلَي firstDate وendDate يمثّلان تاريخَي البدء والانتهاء لنافذة تجميع البيانات. مثال:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

يتيح ذلك فهمًا أفضل للبيانات وما إذا كانت قد تم تحديثها بعد لذلك اليوم أو تعرض البيانات نفسها المعروضة بالأمس.

يُرجى العِلم أنّ واجهة برمجة التطبيقات CrUX API تتأخَّر يومين تقريبًا من تاريخ اليوم، لأنّها تنتظر البيانات المكتملة لهذا اليوم، ويستغرق الأمر بعض الوقت لمعالجة البيانات قبل أن تصبح متاحة في واجهة برمجة التطبيقات. إنّ المنطقة الزمنية المستخدَمة هي توقيت المحيط الهادئ (PST) بدون أي تغييرات مرتبطة بالتوقيت الصيفي.

أمثلة على طلبات البحث

يتم إرسال طلبات البحث ككائنات JSON باستخدام طلب POST إلى https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" مع بيانات طلب البحث ككائن JSON في نص POST:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

على سبيل المثال، يمكن طلب ذلك من curl باستخدام سطر الأوامر التالي (مع استبدال API_KEY بمفتاحك):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

تتوفر البيانات على مستوى الصفحة من خلال واجهة برمجة التطبيقات عن طريق تمرير السمة url في طلب البحث، بدلاً من origin:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

إذا لم يتم ضبط السمة metrics، سيتم عرض جميع المقاييس المتاحة:

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay (متوقّفة نهائيًا)
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (يتم الإبلاغ فقط في حال عدم تحديد formFactor في الطلب)

في حال عدم تقديم قيمة formFactor، سيتم تجميع القيم في جميع أشكال الأجهزة.

يمكنك الاطّلاع على مقالة استخدام Chrome UX Report API للحصول على مزيد من الأمثلة على طلبات البحث.

مسار البيانات

تتم معالجة مجموعة بيانات "تقرير تجربة المستخدم على Chrome" من خلال مسار لدمج البيانات وتجميعها وتصفيتها قبل أن تصبح متاحة باستخدام واجهة برمجة التطبيقات.

متوسط التحرك

البيانات الواردة في تقرير تجربة المستخدم على Chrome هي متوسط التحرك خلال 28 يومًا للمقاييس المجمّعة. وهذا يعني أنّ البيانات المقدَّمة في "تقرير تجربة المستخدم على Chrome" في أي وقت هي البيانات المجمّعة معًا خلال آخر 28 يومًا.

وهذا يشبه الطريقة التي تجمع بها مجموعة بيانات CrUX في BigQuery التقارير الشهرية.

التحديثات اليومية

يتم تعديل البيانات يوميًا في حوالي الساعة 04:00 حسب التوقيت العالمي المنسَّق. لا توجد اتفاقية مستوى خدمة خاصة بأوقات التحديث، ويتم العمل على أساس أفضل بذل كل يوم.

المخطّط

هناك نقطة نهاية واحدة لواجهة برمجة تطبيقات CrUX API التي تقبل طلبات HTTP POST. تعرض واجهة برمجة التطبيقات record يحتوي على عنصر metrics واحد أو أكثر يتوافق مع بيانات الأداء حول المصدر أو الصفحة المطلوبة.

طلب HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

يستخدم عنوان URL بنية تحويل الترميز gRPC.

نص الطلب

يجب أن يحتوي نص الطلب على بيانات بالبنية التالية:

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
الحقول
effectiveConnectionType

string

نوع الاتصال الفعّال هو بُعد طلب بحث يحدد فئة الشبكة الفعالة التي يجب أن تنتمي إليها بيانات السجل.

يستخدِم هذا الحقل القيمتَين ["offline", "slow-2G", "2G", "3G", "4G"] كما هو محدّد في مواصفات واجهة برمجة التطبيقات الخاصة بمعلومات الشبكة.

ملاحظة: إذا لم يتم تحديد نوع اتصال فعّال، سيتم عرض سجلّ خاص يحتوي على بيانات مجمّعة على مستوى كل أنواع الاتصال الفعّالة.
formFactor

enum (FormFactor)

شكل الجهاز هو سمة طلب بحث تحدِّد فئة الجهاز التي يجب أن تنتمي إليها بيانات السجلّ.

يستخدم هذا الحقل القيم DESKTOP أو PHONE أو TABLET.

ملاحظة: إذا لم يتم تحديد أي شكل من أشكال الأجهزة، سيتم عرض سجل خاص يحتوي على بيانات مجمّعة لجميع أشكال الأجهزة.
metrics[]

string

تمثّل هذه السمة المقاييس التي يجب تضمينها في الردّ. وإذا لم يتم تحديد أي مقاييس، سيتم عرض أي مقاييس يتم العثور عليها.

القيم المسموح بها: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
حقل الاتحاد url_pattern url_pattern هو المعرّف الرئيسي للبحث عن سجلّ. يمكن أن تكون الحالة واحدة فقط مما يلي:
origin

string

يشير "المصدر" url_pattern إلى نمط عنوان URL الذي يمثّل أصل الموقع الإلكتروني.

أمثلة: "https://example.com" و"https://cloud.google.com"
url

string

تشير السمة url url_pattern إلى نمط عنوان URL يمثّل أي عنوان URL عشوائي.

أمثلة: "https://example.com/ وhttps://cloud.google.com/why-google-cloud/"

على سبيل المثال، لطلب عرض أكبر محتوى مرئي على الصفحة الرئيسية لمستندات مطوّري برامج Chrome، يُرجى اتّباع الخطوات التالية:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

نص الاستجابة

تعرض الطلبات الناجحة استجابات تحتوي على كائن record وurlNormalizationDetails بالبنية التالية:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

على سبيل المثال، يمكن أن يكون الرد على نص الطلب في الطلب السابق:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

المفتاح

تحدّد Key جميع السمات التي تعتبر هذا السجلّ فريدة.

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
الحقول
formFactor

enum (FormFactor)

شكل الجهاز هو فئة الجهاز التي استخدمها جميع المستخدمين للوصول إلى الموقع الإلكتروني لهذا السجلّ.

وفي حال عدم تحديد شكل الجهاز، سيتم عرض البيانات المجمّعة على مستوى كل أشكال الأجهزة.
effectiveConnectionType

string

نوع الاتصال الفعال هو فئة الاتصال العامة التي اختبرها جميع المستخدمين لهذا السجل. يستخدم هذا الحقل القيم ["بلا إنترنت" أو "بطيء-2G" أو "2G" أو "شبكة الجيل الثالث" أو "4G"] كما هو محدَّد في: https://wicg.github.io/netinfo/#effective-connection-types

وإذا لم يتم تحديد نوع الاتصال الفعلي، سيتم عرض البيانات المجمّعة من كل أنواع الاتصالات الفعالة.
حقل الاتحاد url_pattern نمط عنوان URL هو عنوان URL الذي ينطبق عليه السجل. يمكن أن يكون الحقل "url_pattern" واحدًا فقط مما يلي:
origin

string

يحدّد origin مصدر هذا السجلّ.

ملاحظة: عند تحديد origin، يتم تجميع بيانات عمليات التحميل ضمن هذا المصدر في جميع الصفحات ضمن بيانات تجربة المستخدم على مستوى المصدر.
url

string

يحدّد url عنوان URL محددًا لهذا السجلّ.

ملاحظة: عند تحديد url، سيتم تجميع بيانات لعنوان URL المعني فقط.

المقاييس

metric عبارة عن مجموعة من البيانات المجمّعة لتجربة المستخدم لمقياس واحد للأداء على الويب، مثل سرعة عرض أول محتوى مرئي. وقد يتضمّن ملخّصًا تكراريًا لملخّص استخدام Chrome في الواقع كسلسلة من bins، أو بيانات مئوية محددة (مثل p75)، أو قد يتضمّن كسورًا مُصنَّفة.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

أو

{
  "fractions": {
    object (Fractions)
  }
}
الحقول
histogram[]

object (Bin)

المدرّج التكراري لتجارب المستخدم لمقياس معيّن. سيحتوي المدرج التكراري على سلة واحدة على الأقل وستبلغ كثافات كل السلال ما يصل إلى 1.
percentiles

object (Percentiles)

الشرائح المئوية المفيدة الشائعة للمقياس. سيكون نوع قيمة النسب المئوية مماثلاً لأنواع القيم المحددة لسلال المدرج التكراري.
fractions

object (Fractions)

يحتوي هذا الكائن على كسور مصنَّفة يبلغ مجموعها 1 تقريبًا.

يتم تقريب الكسور إلى 4 منازل عشرية.

صندوق

bin هو جزء منفصل من البيانات يمتد من البداية إلى النهاية، أو إذا لم يتم تحديد أي نهاية من البداية إلى ما لا نهاية موجبة.

يتم تحديد قيم البداية والنهاية في السلة حسب نوع قيمة المقياس الذي تمثله. على سبيل المثال، يتم قياس سرعة عرض أول محتوى مرئي بالمللي ثانية ويتم عرضه كوحدات منفصلة. وبالتالي، ستستخدم سلال المقاييس int32 أنواع البداية والنهاية الخاصة بها. ومع ذلك، يتم قياس متغيّرات التصميم التراكمية بكسور عشرية بدون وحدات ويتم عرضها كرقم عشري مرمّز كسلسلة، وبالتالي ستستخدم سلال المقاييس الخاصة بها سلاسل لنوع القيمة.

{
  "start": value,
  "end": value,
  "density": number
}
الحقول
start

(integer | string)

البداية هي بداية سلة البيانات.
end

(integer | string)

النهاية هي نهاية سلة البيانات. إذا لم تتم تعبئة النهاية، هذا يعني أنّ السلة ليس لها نهاية وتكون صالحة من البداية إلى +inf.
density

number

يعرِض هذا المقياس نسبة المستخدمين الذين لاحظوا قيمة هذه السلة للمقياس المحدّد.

يتم تقريب الكثافات إلى 4 منازل عشرية.

الشرائح المئوية

يحتوي Percentiles على قيم اصطناعية لمقياس بنسبة مئوية إحصائية معينة. وتُستخدم هذه القيم لتقدير قيمة المقياس وفقًا لنسبة المستخدِمين من إجمالي عدد المستخدِمين.

{
  "P75": value
}
الحقول
p75

(integer | string)

اختبرت 75% من عمليات تحميل الصفحات المقياس المعني عند هذه القيمة أو أقل منها.

الكسور

يحتوي Fractions على كسور مصنفة يصل مجموعها إلى 1 تقريبًا. تصف كل تسمية تحميل صفحة بطريقة ما، بحيث يمكن اعتبار المقاييس الممثلة بهذه الطريقة على أنها إنتاج قيم مميزة بدلاً من قيم رقمية، وتعبر الكسور عن عدد مرات قياس قيمة مميزة معينة.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

على غرار قيم الكثافة في سلال المدرّجات التكرارية، يكون كل fraction رقمًا 0.0 <= value <= 1.0 ويصل مجموعه إلى 1.0 تقريبًا.

UrlNormalization

عنصر يمثّل إجراءات التسوية التي تم اتخاذها لتسوية عنوان URL من أجل تحقيق فرصة أعلى للبحث الناجح. هذه هي التغييرات المبرمَجة البسيطة التي يتم إجراؤها عند البحث عن url_pattern المقدّم. لا يتم التعامل مع الإجراءات المعقدة مثل متابعة عمليات إعادة التوجيه.

{
  "originalUrl": string,
  "normalizedUrl": string
}
الحقول
originalUrl

string

عنوان URL الأصلي المطلوب قبل أي إجراءات تسوية.
normalizedUrl

string

عنوان URL بعد أي إجراءات تسوية. هذا عنوان URL صالح لتجربة المستخدم يمكن البحث عنها بشكل معقول.

حدود المعدل

تقتصر واجهة برمجة تطبيقات CrUX API على 150 طلب بحث في الدقيقة لكل مشروع على Google Cloud، ويتم تقديم هذه الواجهة بدون رسوم. ويمكن الاطّلاع على هذا الحد وعلى استخدامك الحالي في Google Cloud Console. ويجب أن تكون هذه الحصة الكبيرة كافية للغالبية العظمى من حالات الاستخدام ولا يمكن الدفع مقابل حصة أكبر.