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

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

جرِّبه الآن

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

تسمح واجهة برمجة التطبيقات CrUX API بطلب البحث عن مقاييس تجربة المستخدم لعنوان URI محدّد، مثل "الحصول على مقاييس لمصدر 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.

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

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

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

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

{
  "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	منزلة مؤلفة من 4 عشرية	النسبة المئوية	الربط من شكل الجهاز إلى كسر	أشكال الأجهزة
navigation_types	منزلة مؤلفة من 4 عشرية	النسبة المئوية	التعيين من نوع التنقل إلى الكسر	أنواع التنقّل
round_trip_time	int	مللي ثانية	الشرائح المئوية مع p75	rtt

ربط اسم مقياس 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
round_trip_time	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 للاطّلاع على مزيد من الأمثلة على طلبات البحث.

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

تتم معالجة مجموعة بيانات 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.

نص الطلب

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

{
  "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"] كما هو محدّد في مواصفات Network Information API ملاحظة: إذا لم يتم تحديد نوع اتصال فعّال، فسيتم عرض سجل خاص يحتوي على بيانات مجمّعة عبر جميع أنواع الاتصال الفعّالة.
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 نوع الاتصال الفعّال هو فئة الاتصال العامة التي واجهها جميع المستخدمين لهذا السجلّ. يستخدم هذا الحقل القيم ["offline" و"slow-2G" و"2G" و"3G" و"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 هي جزء منفصل من البيانات يمتد من البداية إلى النهاية، أو إذا لم يتم تحديد أي نهاية من البداية إلى اللانهاية الموجبة.

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

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

الحقول
start	(integer | string) البداية هي بداية سلة البيانات.
end	(integer | string) End هي نهاية سلة البيانات. إذا لم تتم تعبئة الانتهاء، فهذا يعني أن السلة لا تحتوي على نهاية وتكون صالحة من البداية إلى +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. يجب أن تكون هذه الحصة الكبيرة كافية للغالبية العظمى من حالات الاستخدام، ولا يمكن الدفع مقابل حصة أكبر.