CrUX API

CrUX API, পৃষ্ঠা ও অরিজিন গ্র্যানুলারিটিতে, প্রকৃত ব্যবহারকারীর অভিজ্ঞতা সম্পর্কিত মোট ডেটায় কম-লেটেন্সি অ্যাক্সেস প্রদান করে।

এটি ব্যবহার করে দেখুন!

সাধারণ ব্যবহারিক প্রয়োগ

CrUX API, "https://example.com অরিজিনের জন্য মেট্রিক পান"-এর মতো নির্দিষ্ট URI-এর জন্য ব্যবহারকারীর অভিজ্ঞতা সংক্রান্ত মেট্রিক কোয়েরি করার অনুমতি দেয়।

CrUX API Key

CrUX API ব্যবহার করার জন্য Chrome UX Report API ব্যবহারের জন্য Google Cloud API কী প্রয়োজন।

API key পাওয়া ও ব্যবহার করা

অথবা ক্রেডেনশিয়াল পৃষ্ঠায় একটি তৈরি করুন।

API কী পাওয়ার পরে, আপনার অ্যাপ্লিকেশন সব অনুরোধের URL-এ কোয়েরি প্যারামিটার key=yourAPIKey যোগ করতে পারবে।

URL-এ এম্বেড করার জন্য API কী নিরাপদ; এর কোনও এনকোডিং প্রয়োজন নেই।

কোয়েরির উদাহরণ দেখুন।

ডেটা মডেল

এই বিভাগে অনুরোধ ও উত্তরে ডেটার স্ট্রাকচার সম্পর্কে বিস্তারিত তথ্য দেওয়া হয়েছে।

রেকর্ড করুন

কোনও পৃষ্ঠা বা সাইট সম্পর্কে একটি বিচ্ছিন্ন তথ্য। কোনও রেকর্ডে এমন ডেটা থাকতে পারে যা কোনও শনাক্তকারী এবং ডাইমেনশনের নির্দিষ্ট কম্বিনেশনের জন্য নির্দিষ্ট। একটি রেকর্ডে এক বা একাধিক মেট্রিকের ডেটা থাকতে পারে।

আইডেন্টিফায়ার

কোন রেকর্ড খুঁজে দেখতে হবে তা শনাক্তকারী নির্দিষ্ট করে। CrUX-এ এইসব শনাক্তকারী হল ওয়েবপেজ ও ওয়েবসাইট।

অরিজিন

শনাক্তকারী যদি কোনও অরিজিন হয়, তাহলে সেই অরিজিনের সব পৃষ্ঠার জন্য উপলভ্য সব ডেটা একসাথে এগ্রিগেট করা হয়। যেমন, ধরুন http://www.example.com অরিজিনে এই সাইটম্যাপের লেআউট অনুযায়ী পৃষ্ঠা ছিল:

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

এর অর্থ হল, http://www.example.com-এ সেট করা অরিজিন সহ Chrome UX Report কোয়েরি করলে, http://www.example.com/, http://www.example.com/foo.html ও http://www.example.com/bar.html-এর ডেটা একসাথে এগ্রিগেট করে দেখানো হবে, কারণ সেগুলি সবই ওই অরিজিনের অধীনে থাকা পৃষ্ঠা।

ইউআরএল

শনাক্তকারীটি URL হলে, শুধুমাত্র সেই নির্দিষ্ট URL-এর ডেটা ফেরত দেওয়া হবে। http://www.example.com মূল সাইটম্যাপ আবার দেখা হচ্ছে:

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

শনাক্তকারী যদি http://www.example.com/foo.html ভ্যালু সহ URL-এ সেট করা থাকে, তাহলে শুধু সেই পৃষ্ঠার ডেটা দেখানো হবে।

আকার

ডাইমেনশন ডেটার একটি নির্দিষ্ট গ্রুপকে শনাক্ত করে যার বিপরীতে একটি রেকর্ড একত্রিত করা হচ্ছে, উদাহরণস্বরূপ PHONE-এর ফর্ম ফ্যাক্টর নির্দেশ করে যে রেকর্ডে মোবাইল ডিভাইসে হওয়া লোড সম্পর্কে তথ্য রয়েছে। প্রতিটি ডাইমেনশনের নির্দিষ্ট সংখ্যক ভ্যালু থাকবে এবং সেই ডাইমেনশন উল্লেখ না করার অর্থ হল, ডাইমেনশনটি সব ভ্যালু জুড়ে অ্যাগ্রিগেট করা হয়েছে। যেমন, কোনও ফর্ম ফ্যাক্টর উল্লেখ না করার অর্থ হল, রেকর্ডে যেকোনও ফর্ম ফ্যাক্টরে হওয়া লোড সংক্রান্ত তথ্য আছে।

ফর্ম ফ্যাক্টর

শেষ ব্যবহারকারী পৃষ্ঠা নেভিগেট করার জন্য যে ডিভাইস ক্লাস ব্যবহার করেছেন। এটি ডিভাইসের একটি সাধারণ ক্লাস যা PHONE, TABLET এবং DESKTOP-এ বিভক্ত।

মেট্রিক

আমরা হিস্টোগ্রাম, পার্সেন্টাইল ও ফ্র‍্যাকশন হিসেবে পরিসংখ্যানগত অ্যাগ্রিগেশন হিসেবে মেট্রিক রিপোর্ট করি।

ফ্লোটিং পয়েন্ট ভ্যালু দশমিকের পরে ৪টি সংখ্যা পর্যন্ত রাউন্ড অফ করা হয় (মনে রাখবেন যে cumulative_layout_shift মেট্রিক হল স্ট্রিং হিসেবে এনকোড করা ডাবল, তাই ফ্লোট হিসেবে বিবেচনা করা হয় না এবং স্ট্রিংয়ের মধ্যে দশমিকের পরে ২টি সংখ্যা পর্যন্ত রিপোর্ট করা হয়)।

হিস্টোগ্রাম

হিস্টোগ্রামে মেট্রিক দেখানো হলে, সেই মেট্রিকের জন্য নির্দিষ্ট রেঞ্জের মধ্যে থাকা পৃষ্ঠা লোডের শতাংশ আমরা দেখাই।

একটি উদাহরণ মেট্রিকের জন্য তিন বিন হিস্টোগ্রাম এইরকম দেখতে হয়:

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

এই ডেটা থেকে বোঝা যায় যে ৩৮.১৮% পৃষ্ঠা লোডের ক্ষেত্রে, উদাহরণ মেট্রিক ০ মিলি সেকেন্ড থেকে ১,০০০ মিলি সেকেন্ডের মধ্যে পরিমাপ করা হয়েছে। এই হিস্টোগ্রামে মেট্রিকের ইউনিট নেই, এই ক্ষেত্রে আমরা মিলিসেকেন্ড ধরে নেব।

এছাড়াও, পৃষ্ঠা লোড হওয়ার ৪৯.৯১% ক্ষেত্রে ১,০০০ms থেকে ৩,০০০ms-এর মধ্যে মেট্রিক ভ্যালু দেখা গেছে এবং ১১.৯২% ক্ষেত্রে ৩,০০০ms-এর বেশি ভ্যালু দেখা গেছে।

পার্সেন্টাইল

মেট্রিকে পার্সেন্টাইলও থাকতে পারে যা অতিরিক্ত বিশ্লেষণের জন্য উপযোগী হতে পারে। আমরা সেই মেট্রিকের জন্য প্রদত্ত পার্সেন্টাইলে নির্দিষ্ট মেট্রিক ভ্যালু রিপোর্ট করি। এগুলি উপলভ্য ডেটার সম্পূর্ণ সেটের উপর ভিত্তি করে তৈরি করা হয় এবং চূড়ান্ত বিন করা ডেটার উপর ভিত্তি করে তৈরি করা হয় না, তাই এগুলি চূড়ান্ত বিন করা হিস্টোগ্রামের উপর ভিত্তি করে তৈরি করা ইন্টারপোলেটেড পার্সেন্টাইলের সাথে নাও মিলতে পারে।

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

এই উদাহরণে, অন্তত ৭৫% পৃষ্ঠা লোড হওয়ার সময় মেট্রিক ভ্যালু <= 2063 দিয়ে পরিমাপ করা হয়েছে।

ভগ্নাংশ

ভগ্নাংশ থেকে বোঝা যায় যে কত শতাংশ পৃষ্ঠা লোডকে নির্দিষ্টভাবে লেবেল করা যেতে পারে। এই ক্ষেত্রে, মেট্রিক ভ্যালু হল এইসব লেবেল।

যেমন, form_factors মেট্রিকটি একটি fractions অবজেক্ট নিয়ে গঠিত যা প্রদত্ত কোয়েরি কভার করে এমন ফর্ম ফ্যাক্টর (বা ডিভাইস)-এর ব্রেকডাউন তালিকাভুক্ত করে:

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

এই ক্ষেত্রে, ডেস্কটপে ৩.৭৭%, ট্যাবলেটে ২.৮৮% এবং ফোনে ৯৩.৩৫% পৃষ্ঠা লোড পরিমাপ করা হয়েছে, যা মোট ১০০%।

মেট্রিক ভ্যালুর ধরন

BigQuery মেট্রিক নামের ম্যাপিং

সংগ্রহের মেয়াদ

অক্টোবর ২০২২ থেকে, CrUX API-তে collectionPeriod অবজেক্ট রয়েছে যার মধ্যে firstDate ও endDate ফিল্ড আছে এবং এগুলি অ্যাগ্রিগেশন উইন্ডোর শুরু ও শেষের তারিখ দেখায়। যেমন:

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

এর ফলে ডেটা আরও ভালোভাবে বোঝা যায় এবং সেই দিনের জন্য এটি আপডেট করা হয়েছে কিনা বা গতকালের মতো একই ডেটা দেখাচ্ছে কিনা তা জানা যায়।

সংগ্রহের মেয়াদ PageSpeed Insights-এও উপলভ্য:

এছাড়াও, collectionPeriod-এ সবসময় ২৮ দিনের ডেটা দেখানো হবে, এমনকি ডেটা যদি পুরো ২৮ দিনের জন্য না হয় (যেমন, কোনও পৃষ্ঠা ২৮ দিনের কম সময় আগে লঞ্চ করা হলে)। collectionPeriod হল সেই সময়সীমা যার মধ্যে CrUX ডেটা একত্রিত করা হয়েছে, তবে এটি ডেটা যে সময়সীমাকে উপস্থাপন করে তা নাও হতে পারে।

কোয়েরির উদাহরণ

কোয়েরি ডেটা সহ https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"-এ POST অনুরোধ ব্যবহার করে JSON অবজেক্ট হিসেবে কোয়েরি জমা দেওয়া হয়, POST বডিতে JSON অবজেক্ট হিসেবে:

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

যেমন, নিম্নলিখিত কমান্ড লাইন (API_KEY-এর জায়গায় আপনার কী ব্যবহার করে) ব্যবহার করে curl থেকে এটি কল করা যেতে পারে:

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"]}'

API-এর মাধ্যমে পৃষ্ঠা-লেভেল ডেটা পাওয়া যায়, এর জন্য origin-এর পরিবর্তে কোয়েরিতে url প্রপার্টি পাস করতে হয়:

{
  "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 UX Report API ব্যবহার করা দেখুন।

ডেটা পাইপলাইন

API ব্যবহার করে উপলভ্য হওয়ার আগে, CrUX ডেটাসেটকে পাইপলাইনের মাধ্যমে প্রসেস করে ডেটা একত্রিত, এগ্রিগেট ও ফিল্টার করা হয়।

রোলের গড়

Chrome UX Report-এর ডেটা হল ২৮ দিনের রোলিং অ্যাভারেজ অ্যাগ্রিগেটেড মেট্রিক। এর অর্থ হল, যেকোনও সময়ে Chrome UX Report-এ দেখানো ডেটা আসলে গত ২৮ দিনের মোট ডেটা।

BigQuery-তে CrUX ডেটাসেট যেভাবে মাসিক রিপোর্ট একত্রিত করে, এটিও সেইভাবেই কাজ করে।

দৈনিক আপডেট

প্রতিদিন প্রায় ০৪:০০ UTC-তে ডেটা আপডেট করা হয়। আপডেট করার সময়ের জন্য কোনও পরিষেবা লেভেল এগ্রিমেন্ট নেই; এটি প্রতিদিন যথাসাধ্য চেষ্টা করার ভিত্তিতে চালানো হয়।

স্কিমা

CrUX API-এর জন্য একটিই এন্ডপয়েন্ট আছে যা POST HTTP অনুরোধ গ্রহণ করে। API একটি 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 ডেভেলপার ডকুমেন্টেশন হোমপেজের জন্য ডেস্কটপ Largest Contentful Paint ভ্যালুর অনুরোধ করতে:

{
  "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 হল একটি ওয়েব পারফর্ম্যান্স মেট্রিকের জন্য একত্রিত করা ব্যবহারকারীর অভিজ্ঞতা সংক্রান্ত ডেটার একটি সেট, যেমন ফার্স্ট কনটেন্টফুল পেইন্ট। এতে bins-এর সিরিজ হিসেবে বাস্তব জগতে Chrome ব্যবহারের সারসংক্ষেপ হিস্টোগ্রাম, নির্দিষ্ট পার্সেন্টাইল ডেটা (যেমন p75) থাকতে পারে অথবা এতে লেবেল করা ভগ্নাংশ থাকতে পারে।

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

অথবা

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

বিন

bin হল ডেটার একটি বিচ্ছিন্ন অংশ যা শুরু থেকে শেষ পর্যন্ত বিস্তৃত, অথবা যদি কোনও শেষ না দেওয়া হয় তবে শুরু থেকে ধনাত্মক অনন্ত পর্যন্ত।

বিন যে মেট্রিককে দেখায়, সেই মেট্রিকের ভ্যালু টাইপে বিনের শুরু ও শেষের ভ্যালু দেওয়া হয়। যেমন, ফার্স্ট কন্টেন্টফুল পেইন্টকে মিলি সেকেন্ডে পরিমাপ করা হয় এবং int হিসেবে দেখানো হয়, তাই এর মেট্রিক বিনের স্টার্ট ও এন্ড টাইপের জন্য int32 ব্যবহার করা হবে। তবে, কিউমুলেটিভ লেআউট শিফ্ট ইউনিটলেস দশমিক সংখ্যায় পরিমাপ করা হয় এবং স্ট্রিং হিসেবে এনকোড করা দশমিক সংখ্যা হিসেবে দেখানো হয়, তাই এর মেট্রিক বিন ভ্যালু টাইপের জন্য স্ট্রিং ব্যবহার করবে।

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

পার্সেন্টাইল

Percentiles-এ প্রদত্ত পরিসংখ্যানগত পার্সেন্টাইলে কোনও মেট্রিকের সিন্থেটিক ভ্যালু থাকে। মোট ব্যবহারকারীর সংখ্যার মধ্যে থেকে শতাংশ হিসেবে ব্যবহারকারীদের অভিজ্ঞতা অনুযায়ী মেট্রিকের ভ্যালু অনুমান করার জন্য এগুলি ব্যবহার করা হয়।

{
  "P75": value
}

ভগ্নাংশ

Fractions-এ লেবেল করা ভগ্নাংশ রয়েছে যেগুলি যোগ করলে ~১ হয়। প্রতিটি লেবেল কোনও না কোনওভাবে পৃষ্ঠা লোড হওয়ার ঘটনাকে বর্ণনা করে, তাই এইভাবে দেখানো মেট্রিককে সংখ্যাগত মানের পরিবর্তে স্বতন্ত্র মান হিসেবে বিবেচনা করা যেতে পারে এবং ভগ্নাংশটি দেখায় যে কত ঘন ঘন একটি নির্দিষ্ট স্বতন্ত্র মান পরিমাপ করা হয়েছে।

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

হিস্টোগ্রাম বিনের ঘনত্ব ভ্যালুর মতো, প্রতিটি fraction হল একটি সংখ্যা 0.0 <= value <= 1.0 এবং সেগুলি যোগ করলে ~১.০ হয়।

UrlNormalization

অবজেক্ট যা একটি URL স্বাভাবিক করার জন্য গৃহীত স্বাভাবিককরণ ক্রিয়াগুলিকে উপস্থাপন করে যাতে সফল লুকআপের উচ্চ সম্ভাবনা অর্জন করা যায়। এগুলি হল প্রাথমিক, অটোমেটিক পরিবর্তন যা প্রদান করা url_pattern খোঁজার সময় ব্যর্থ হবে বলে জানা থাকলে করা হয়। রিডাইরেক্ট ফলো করার মতো জটিল অ্যাকশন ম্যানেজ করা হয় না।

{
  "originalUrl": string,
  "normalizedUrl": string
}

রেট লিমিট

CrUX API-এর ক্ষেত্রে, Google Cloud প্রোজেক্ট পিছু প্রতি মিনিটে ১৫০টি কোয়েরি করা যায় এবং এর জন্য কোনও চার্জ লাগে না। এই সীমা এবং আপনার বর্তমান ব্যবহার Google Cloud Console-এ দেখা যেতে পারে। এই কোটা বেশিরভাগ ব্যবহারের ক্ষেত্রে যথেষ্ট এবং কোটা বাড়ানোর জন্য পেমেন্ট করা সম্ভব নয়।