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

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

جرِّبه الآن

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

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

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

يتطلّب استخدام CrUX API توفير مفتاح Google Cloud API لاستخدامه مع Chrome UX Report API.

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

أو يمكنك إنشاء مفتاح في صفحة "بيانات الاعتماد".

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إضافة مَعلمة طلب البحث key=yourAPIKey إلى جميع عناوين 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.

المقياس

نقدّم تقارير عن مقاييس التتبُّع في شكل تجميعات إحصائية، في مدرّجات تكرارية ونسب مئوية وأجزاء.

يتم تقريب قيم الفاصلة العائمة إلى 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 في المجموع.

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

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

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

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

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

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

تتوفّر فترة جمع البيانات أيضًا في "إحصاءات PageSpeed":

بالإضافة إلى ذلك، سيعرض collectionPeriod دائمًا بيانات آخر 28 يومًا، حتى إذا لم تكن البيانات تغطي هذه الفترة بالكامل (على سبيل المثال، إذا تم إطلاق صفحة قبل أقل من 28 يومًا). collectionPeriod هي الفترة الزمنية التي تمّ تجميع بيانات CrUX خلالها، وليس بالضرورة الفترة الزمنية التي تمثّلها البيانات.

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

يتم إرسال طلبات البحث كعناصر 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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• ‫form_factors (يتم الإبلاغ عنها فقط في حال عدم تحديد formFactor في الطلب)
• experimental_ad_count (يتمّ تسجيلها فقط للصفحات المضمّنة في مقاييس الإعلانات)
• ‫experimental_ad_density (يتم الإبلاغ عنها فقط للصفحات المضمّنة في مقاييس الإعلانات)
• experimental_ad_cpu (يتمّ تسجيلها فقط للصفحات المضمّنة في مقاييس الإعلانات)
• experimental_ad_kilobytes (يتمّ تسجيلها فقط للصفحات المضمّنة في مقاييس الإعلانات)

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

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

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

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

المتوسط المتحرّك

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

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

تعديلات يومية

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

المخطط

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

طلب HTTP

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

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

نص الطلب

يجب أن يتضمن نص الطلب بيانات بالبنية التالية:

{
  "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.
}

على سبيل المثال، لطلب قيم سرعة عرض أكبر محتوى مرئي على أجهزة الكمبيوتر للصفحة الرئيسية لمستندات مطوّري 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 جميع السمات التي تحدّد هذا السجلّ على أنّه فريد.

{
  "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.
}

المقاييس

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

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

أو

{
  "fractions": {
    object (Fractions)
  }
}

المربع

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

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

{
  "start": value,
  "end": value,
  "density": number
}

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

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

{
  "P75": value
}

الكسور

تحتوي 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
}

الحدود القصوى لمعدّل الاستخدام

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