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

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

جرِّبه الآن

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

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

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

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

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

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

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

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

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

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

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

تسجيل

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

المعرفات

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

الأصل

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

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

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

بالإضافة إلى ذلك، سيعرِض الرمز collectionPeriod دائمًا آخر 28 يومًا، حتى إذا لم تكن البيانات تخصّ آخر 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
• navigation_types
• form_factors (لا يتم الإبلاغ عنها إلا إذا لم يتم تحديد formFactor في الطلب)

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

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

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

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

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

البيانات الواردة في تقرير تجربة المستخدِم في 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.

نص الطلب

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

{
  "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 هو جزء منفصل من البيانات يمتد من البداية إلى النهاية، أو إذا لم يتم تحديد نهاية، يمتد من البداية إلى ما لا نهاية.

يتمّ تقديم قيم بداية الحزمة ونهايتها في نوع قيمة المقياس الذي تمثّله. على سبيل المثال، يتم قياس أوّل مرّة ظهور للمحتوى بالملي ثانية ويتم عرضها كأرقام صحيحة، وبالتالي ستستخدم حِزم المقاييس أرقامًا صحيحة من النوع int32 لأنواع البدء والانتهاء. ومع ذلك، يتم قياس "تغيُّر المخطّط التراكمية" بقيم عشرية بدون وحدات ويتم عرضها كقيمة عشرية مُشفَّرة كسلسلة، وبالتالي ستستخدم حِزم المقاييس سلاسل لنوع القيمة.

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

النِسب المئوية

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

{
  "P75": value
}

الكسور

يحتوي Fractions على أجزاء مصنّفة تبلغ مجموعها تقريبًا 1. يصف كل تصنيف loading load page بطريقة ما، لذا يمكن اعتبار المقاييس التي يتم تمثيلها بهذه الطريقة أنّها تُنتج قيمًا مميزة بدلاً من القيم الرقمية، وتُعبّر الكسور عن معدّل تكرار قياس قيمة مميزة معيّنة.

{
  "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. من المفترض أن تكون هذه الحصة الكبيرة كافية لمعظم حالات الاستخدام، ولا يمكن الدفع مقابل حصة أكبر.