تتيح واجهة برمجة التطبيقات CrUX API الوصول في وقت استجابة سريع إلى البيانات المجمّعة لتجربة المستخدم الفعلي بدقة الصفحة والأصل.
حالة الاستخدام الشائعة
تسمح واجهة برمجة التطبيقات CrUX API بطلب البحث عن مقاييس تجربة المستخدم لعنوان URI محدّد، مثل "الحصول على مقاييس لمصدر https://example.com
".
مفتاح واجهة برمجة تطبيقات CrUX
يتطلب استخدام واجهة برمجة التطبيقات CrUX مفتاح Google Cloud API. يمكنك إنشاء حساب في صفحة بيانات الاعتماد وتوفيره لاستخدام Chrome UX Report API
.
بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق معلَمة طلب البحث key=[YOUR_API_KEY]
بجميع عناوين 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% من عمليات تحميل الصفحات شهدت قيمة أكبر من 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 |
منزلة مؤلفة من 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 |
نوع الاتصال الفعّال هو بُعد طلب بحث يحدد فئة الشبكة الفعّالة التي يجب أن تنتمي إليها بيانات السجلّ. يستخدم هذا الحقل القيم ملاحظة: إذا لم يتم تحديد نوع اتصال فعّال، فسيتم عرض سجل خاص يحتوي على بيانات مجمّعة عبر جميع أنواع الاتصال الفعّالة. |
formFactor |
شكل الجهاز هو سمة طلب بحث تحدِّد فئة الجهاز التي يجب أن تنتمي إليها بيانات السجلّ. يستخدم هذا الحقل القيم ملاحظة: إذا لم يتم تحديد أي شكل من أشكال الأجهزة، فسيتم عرض سجل خاص يحتوي على بيانات مجمعة على جميع أشكال الأجهزة. |
metrics[] |
المقاييس التي يجب تضمينها في الرد. وفي حال عدم تحديد أي منها، سيتم عرض أي مقاييس تم العثور عليها. القيم المسموح بها: |
حقل الاتحاد url_ . url_pattern هو المعرّف الرئيسي للبحث عن سجلّ. يمكن أن تكون الحالة واحدة فقط مما يلي: |
|
origin |
يشير "المصدر" في أمثلة: |
url |
تشير علامة أمثلة: |
على سبيل المثال، لطلب أكبر قيم لسرعة عرض أكبر جزء من المحتوى على سطح المكتب في الصفحة الرئيسية لمستندات مطوّري برامج 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 |
شكل الجهاز هو فئة الجهاز التي استخدمها جميع المستخدمين للوصول إلى الموقع الإلكتروني الخاص بهذا السجلّ. إذا لم يتم تحديد شكل الجهاز، سيتم عرض بيانات مجمّعة تتضمن جميع أشكال الأجهزة. |
effectiveConnectionType |
نوع الاتصال الفعّال هو فئة الاتصال العامة التي واجهها جميع المستخدمين لهذا السجلّ. يستخدم هذا الحقل القيم ["offline" و"slow-2G" و"2G" و"3G" و"4G"] كما هو موضّح في: https://wicg.github.io/netinfo/#effective-connection-types إذا لم يتم تحديد نوع الاتصال الفعّال، فسيتم عرض بيانات مجمّعة من جميع أنواع الاتصال الفعّالة. |
حقل الاتحاد url_ . نمط عنوان URL هو عنوان URL الذي ينطبق عليه السجلّ. يمكن أن يكون url_ واحدًا فقط مما يلي: |
|
origin |
تحدّد الدالة ملاحظة: عند تحديد |
url |
تحدّد الدالة ملاحظة: عند تحديد |
المقاييس
metric
هو مجموعة من بيانات تجربة المستخدم المجمّعة لمقياس واحد لأداء الويب، مثل سرعة عرض أول محتوى مرئي.
وقد يحتوي على رسم بياني لملخّص استخدام Chrome في العالم الفعلي كسلسلة من bins
أو بيانات نسبة مئوية محدَّدة
(مثل P75)، أو قد يحتوي على كسور مصنَّفة.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
أو
{
"fractions": {
object (Fractions)
}
}
الحقول | |
---|---|
histogram[] |
المدرّج التكراري لتجارب المستخدم في أحد المقاييس سيحتوي المدرج التكراري على سلة واحدة على الأقل، وسيبلغ مجموع كثافات كل السلال ما يصل إلى 1 تقريبًا. |
percentiles |
الشرائح المئوية المفيدة الشائعة للمقياس سيكون نوع القيمة للقيم المئوية هو نفسه أنواع القيم المحددة لسلال المدرج التكراري. |
fractions |
يحتوي هذا الكائن على كسور مُصنَّفة، والتي يبلغ مجموعها 1 تقريبًا. يتم تقريب الكسور إلى 4 منازل عشرية. |
صندوق
السمة bin
هي جزء منفصل من البيانات يمتد من البداية إلى النهاية، أو إذا لم يتم تحديد أي نهاية من البداية إلى اللانهاية الموجبة.
يتم تحديد قيم البداية والنهاية للسلة في نوع قيمة المقياس الذي يمثله. على سبيل المثال، يتم قياس سرعة عرض أول محتوى مرئي بالملّي ثانية، ويتم عرضه كعدد صحيح، وبالتالي فإنّ سلال البيانات المترية الخاصة بها ستستخدم int32s لتحديد نوعَي البداية والنهاية. ومع ذلك، يتم قياس متغيّرات التصميم التراكمية بعدد عشري لا وحدات، ويتم عرضه كسلسلة عشرية مرمّزة كسلسلة، وبالتالي تستخدِم سلال المقاييس الخاصة بها سلاسل لنوع القيمة الخاص بها.
{
"start": value,
"end": value,
"density": number
}
الحقول | |
---|---|
start |
البداية هي بداية سلة البيانات. |
end |
End هي نهاية سلة البيانات. إذا لم تتم تعبئة الانتهاء، فهذا يعني أن السلة لا تحتوي على نهاية وتكون صالحة من البداية إلى +inf. |
density |
نسبة المستخدمين الذين واجهوا قيمة هذه السلة للمقياس المعني. يتم تقريب الكثافة إلى 4 أماكن عشرية. |
الشرائح المئوية
يحتوي Percentiles
على قيم اصطناعية لمقياس معيّن بنسبة مئوية إحصائية معيّنة. وتُستخدم هذه العوامل لتقدير قيمة المقياس وفقًا لتجربة نسبة من المستخدمين من إجمالي عدد المستخدمين.
{
"P75": value
}
الحقول | |
---|---|
p75 |
شهدت 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 |
عنوان URL الأصلي المطلوب قبل أي إجراءات تسوية. |
normalizedUrl |
عنوان URL بعد أي إجراءات تسوية. هذا عنوان URL صالح لتجربة مستخدم يمكن البحث عنه بشكل معقول. |
حدود المعدل
أما واجهة برمجة التطبيقات CrUX API، فتحتوي على 150 طلب بحث في الدقيقة كحد أقصى لكل مشروع على Google Cloud يتم تقديمه بدون رسوم. ويمكن الاطّلاع على هذا الحدّ واستخدامك الحالي في Google Cloud Console. يجب أن تكون هذه الحصة الكبيرة كافية للغالبية العظمى من حالات الاستخدام، ولا يمكن الدفع مقابل حصة أكبر.