browser.mimeHandler

বিবরণ

থার্ড-পার্টি এক্সটেনশনে MIME-এর প্রকার স্ট্রিম ম্যানেজ করতে chrome.mimeHandler API ব্যবহার করুন।

উপলভ্যতা

Chrome 151+

ম্যানিফেস্ট

এই API ব্যবহার করতে নিম্নলিখিত কীগুলি ম্যানিফেস্টে ঘোষণা করতে হবে।

"mime_types_handler"

ধারণা ও ব্যবহার

আগে, নির্দিষ্ট ধরনের ডকুমেন্ট (যেমন, PDF ভিউয়ার) ম্যানেজ করে এমন থার্ড-পার্টি এক্সটেনশন, নেভিগেশন ক্যাচ করতে এবং ব্যবহারকারীদের এক্সটেনশন পৃষ্ঠায় রিডাইরেক্ট করতে নেটওয়ার্ক রিকোয়েস্ট ইন্টারসেপশনের উপর নির্ভর করত। MIME হ্যান্ডলার হিসেবে রেজিস্টার করলে সেই পদ্ধতির বেশ কিছু সীমাবদ্ধতা এড়ানো যায়:

• আসল URL অ্যাড্রেস বারে থেকে যায় এবং chrome-extension:// URL দিয়ে প্রতিস্থাপিত হয় না।
• আপনার এক্সটেনশন, দ্বিতীয় নেটওয়ার্ক অনুরোধ করার পরিবর্তে, Chrome আগে থেকেই যে উত্তর পেয়েছে তা নিয়ে আসে। POST অনুরোধের মাধ্যমে বা সিঙ্গল-ইউজ URL থেকে পাঠানো ডকুমেন্ট সঠিকভাবে কাজ করে।
• আপনার এক্সটেনশন <embed>, <object> বা <iframe> এলিমেন্টের মধ্যে লোড করা ডকুমেন্ট রেন্ডার করতে পারে।
• ব্যবহারকারী এক্সটেনশনের সেটিংসে "ফাইল URL-এ অ্যাক্সেসের অনুমতি দিন" বিকল্প ম্যানুয়ালি চালু না করলেও লোকাল ফাইল (file:// URL) কাজ করে।

MIME হ্যান্ডলার শুধুমাত্র সেইসব ডকুমেন্টের ক্ষেত্রে প্রযোজ্য হয় যেগুলি সম্পূর্ণ ফ্রেম দখল করে: টপ-লেভেল নেভিগেশন এবং এম্বেড করা ডকুমেন্ট। ইনলাইন সাবরিসোর্সে (যেমন, <audio>, <img> বা <video> এলিমেন্ট) এগুলি কখনও প্রয়োগ করা হয় না।

হ্যান্ডলার রেজিস্টার করুন

আপনার এক্সটেনশনকে MIME হ্যান্ডলার হিসেবে রেজিস্টার করতে, ম্যানিফেস্টে "mime_types_handler" কী ঘোষণা করুন। প্রতিটি এন্ট্রি একটি MIME-এর প্রকারকে এক্সটেনশন পৃষ্ঠায় ম্যাপ করে যা এটিকে রেন্ডার করে:

manifest.json:

{
  "name": "My PDF Viewer",
  ...
  "mime_types_handler": {
    "application/pdf": {
      "handler_url": "viewer.html",
      "can_embed": true
    }
  },
  ...
}

<embed>, <object> বা <iframe> এলিমেন্টে এম্বেড করা ডকুমেন্ট ম্যানেজ করতে "can_embed"-কে true-এ সেট করুন। বাদ দেওয়া হলে, আপনার হ্যান্ডলার শুধুমাত্র টপ-লেভেল নেভিগেশন রিসিভ করে। Chrome 151 থেকে, পাবলিক হ্যান্ডলারের জন্য application/pdf হল একমাত্র উপলভ্য MIME-এর প্রকার; কাজ করে না এমন MIME-এর প্রকার ঘোষণা করলে ইনস্টলেশন সংক্রান্ত সতর্কতা দেখানো হয়।

একাধিক ইনস্টল করা এক্সটেনশন একই MIME-এর প্রকারের জন্য রেজিস্টার করলে, সবচেয়ে সম্প্রতি ইনস্টল করা এক্সটেনশন এটি ম্যানেজ করে। সেই এক্সটেনশন আনইনস্টল করা হলে, আগে ইনস্টল করা হ্যান্ডলার আবার অ্যাক্টিভ হয়ে যায়।

স্ট্রিম সংক্রান্ত তথ্য ফিরিয়ে আনা

কোনও ব্যবহারকারী রেজিস্টার করা MIME টাইপের ডকুমেন্ট খুললে, Chrome তার বিল্ট-ইন ভিউয়ারের পরিবর্তে আপনার হ্যান্ডলার পৃষ্ঠা লোড করে। হ্যান্ডলার পৃষ্ঠা থেকে, StreamInfo অবজেক্ট ফিরিয়ে আনতে getStreamInfo() কল করুন। এর মধ্যে রয়েছে ব্যবহারকারী যে originalUrl-এ নেভিগেট করেছেন, HTTP responseHeaders, ডকুমেন্টটি embedded প্রসঙ্গে লোড করা হয়েছে কিনা এবং একটি streamUrl যা ডকুমেন্টের কন্টেন্ট আনতে ব্যবহার করা যেতে পারে।

streamUrl ঠিক একবারই ফেচ করা যাবে এবং শুধুমাত্র আপনার এক্সটেনশনের উৎস থেকে। প্রসেস করার আগে উত্তরটি সম্পূর্ণ পড়ুন; একই streamUrl দ্বিতীয়বার ফেচ করা যায়নি। ডকুমেন্টের লোকেশন বা শীর্ষক দেখানোর সময় originalUrl ব্যবহার করুন, কন্টেন্ট ফেচ করার জন্য নয়, কারণ আসল অনুরোধটি হয়ত রিপিট করা যাবে না।

মনে রাখবেন: getStreamInfo() শুধুমাত্র হ্যান্ডলার পৃষ্ঠায় কাজ করে যা Chrome কোনও ডকুমেন্টের জন্য লোড করেছে। অন্য এক্সটেনশন কনটেক্সট থেকে এটি কল করা, যেমন পরিষেবা কর্মী বা বিকল্প পৃষ্ঠা, ব্যর্থ হয় কারণ কোনও সংশ্লিষ্ট স্ট্রিম নেই।

নেটিভ হ্যান্ডলারে ফিরে যান

আপনার হ্যান্ডলার এমন ডকুমেন্ট দেখতে পেতে পারে যা এটি রেন্ডার করতে পারে না, যেমন নষ্ট বা পাসওয়ার্ড-সুরক্ষিত ফাইল। ব্যবহারকারীকে একটি ভাঙা পৃষ্ঠায় ছেড়ে দেওয়ার পরিবর্তে, ডকুমেন্ট ম্যানেজ করা বন্ধ করতে এবং Chrome-এর বিল্ট-ইন ভিউয়ারে ফেরত দিতে abortAndFallbackToNativeHandler() কল করুন। ফলব্যাক হিসেবে Chrome আপনার হ্যান্ডলার পৃষ্ঠা আনলোড করে; এই কলের পরে কোনও কোড রান করে না।

আপনার হ্যান্ডলার রান করার সময় Chrome রেসপন্স বাফার করে। আপনি এই পদ্ধতি কল করার সময় সম্পূর্ণ উত্তর পাওয়া গেলে, Chrome নতুন নেটওয়ার্ক রিকোয়েস্ট ছাড়াই বাফার করা কপি থেকে বিল্ট-ইন ভিউয়ার পরিবেশন করে। অন্যথায়, Chrome নেটওয়ার্ক থেকে ডকুমেন্ট রিলোড করে, যা POST বা সিঙ্গল-ইউজ URL-এর মাধ্যমে ডেলিভার করা ডকুমেন্টের ক্ষেত্রে ব্যর্থ হতে পারে। আপনি এটি রেন্ডার করতে পারবেন কিনা তা সিদ্ধান্ত নেওয়ার আগে স্ট্রিমটি সম্পূর্ণভাবে ফেচ করুন; আপনার streamUrl ফেচ করা সম্পূর্ণ হলে, Chrome-এর কাছে সম্পূর্ণ রেসপন্স থাকে।

API-এর উপলভ্যতা ম্যানেজ করা

Chrome 151-এর আগের Chrome ভার্সনে, "mime_types_handler" ঘোষণা করা এক্সটেনশন এখনও ইনস্টল হয় ও চলে, কিন্তু হ্যান্ডলার হিসেবে রেজিস্টার করা হয় না এবং browser.mimeHandler সংজ্ঞায়িত করা হয় না। নেটওয়ার্ক অনুরোধ ইন্টারসেপশন থেকে মাইগ্রেট করা এক্সটেনশন স্টার্টআপে API চেক করতে পারে এবং তাদের বর্তমান পদ্ধতি ফলব্যাক হিসেবে রাখতে পারে:

service-worker.js:

if (browser.mimeHandler) {
  // Chrome routes registered MIME types to the handler page
  // declared in the manifest.
} else {
  // Fall back to network request interception.
}

উদাহরণ

স্ট্রিম ম্যানেজ করা

ম্যানিফেস্টে ঘোষণা করা হ্যান্ডলার পৃষ্ঠায় নিম্নলিখিত উদাহরণটি রান করে। এটি ডকুমেন্টের কন্টেন্ট ফেচ করে এবং রেন্ডার করতে না পারলে Chrome-এর বিল্ট-ইন ভিউয়ারে ফিরে যায়:

viewer.js:

async function loadDocument() {
  const streamInfo = await browser.mimeHandler.getStreamInfo();

  // The `embedded` property is true if the document is loaded
  // within an <embed>, <object>, or <iframe> element.
  if (streamInfo.embedded) {
    // Adjust the UI (e.g., hide the top navigation bar).
    document.body.classList.add('embedded-view');
  }

  // Fetch the content using the provided streamUrl. The stream can
  // only be consumed once, so read it fully before continuing.
  const response = await fetch(streamInfo.streamUrl);
  const data = await response.arrayBuffer();

  try {
    // Render the document (e.g., using PDF.js).
    await renderDocument(data);
  } catch (e) {
    // Can't render this document. Fall back to Chrome's built-in
    // viewer; the page unloads and no code runs after this call.
    browser.mimeHandler.abortAndFallbackToNativeHandler();
  }
}

loadDocument();

ব্যবহারকারীদের হ্যান্ডেল টগল করতে দিন

হ্যান্ডলার বিকল্প MIME-এর প্রকার অনুযায়ী স্টোর করা হয়। নিম্নলিখিত উদাহরণে getMimeHandlerOptions() এবং setMimeHandlerOptions() ব্যবহার করা হয়েছে যাতে ব্যবহারকারীরা এক্সটেনশন আনইনস্টল না করেই বিকল্প পৃষ্ঠা থেকে হ্যান্ডলিং বন্ধ করতে পারেন। হ্যান্ডেল করার সুবিধা বন্ধ করা থাকলে, সেই ধরনের ডকুমেন্ট আর আপনার এক্সটেনশনে পাঠানো হয় না।

options.js:

const checkbox = document.querySelector('#handle-pdfs');

async function initOptions() {
  const options =
      await browser.mimeHandler.getMimeHandlerOptions('application/pdf');
  // Handling is enabled unless it has been explicitly disabled.
  checkbox.checked = options.enabled !== false;
}

checkbox.addEventListener('change', async () => {
  await browser.mimeHandler.setMimeHandlerOptions('application/pdf', {
    enabled: checkbox.checked
  });
});

initOptions();

ধরন

MimeHandlerOptions

প্রপার্টি

• canEmbed

  বুলিয়ান ঐচ্ছিক

  Chrome 157+

  এই হ্যান্ডলারটি এম্বেড করা লোডের (iframe, এম্বেড, অবজেক্ট) জন্য ব্যবহার করা যেতে পারে কিনা। ম্যানিফেস্ট এন্ট্রির can_embed ভ্যালু ডিফল্ট হিসেবে সেট করা হয়। enabled মিথ্যা হলে কোনও প্রভাব পড়ে না।

• সক্ষমিত

  বুলিয়ান ঐচ্ছিক

  এই হ্যান্ডলার চালু করা আছে কিনা। ম্যানিফেস্ট এন্ট্রির enabled ভ্যালু ডিফল্ট হিসেবে সেট করা হয়।

StreamInfo

প্রপার্টি

• এম্বেড করা আছে

  বুলিয়ান

  এম্বেড করা প্রসঙ্গে (iframe/এম্বেড/অবজেক্ট) লোড করা হলে ট্রু।

• mimeType

  স্ট্রিং

  ইন্টারসেপ্ট করা কন্টেন্টের MIME-এর প্রকার।

• originalUrl

  স্ট্রিং

  ব্যবহারকারী যে আসল URL-এ নেভিগেট করেছেন।

• responseHeaders

  অবজেক্ট

  কী-ভ্যালু পেয়ার হিসেবে HTTP রেসপন্স হেডার।

• streamUrl

  স্ট্রিং

  যে URL থেকে স্ট্রিম ডেটা ফেচ করা হবে।

• tabId

  নম্বর

  ডকুমেন্ট সহ ট্যাব আইডি।

পদ্ধতি

abortAndFallbackToNativeHandler()

browser.mimeHandler.abortAndFallbackToNativeHandler(): Promise<void>

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

রিটার্ন

• <void> প্রমিস

getMimeHandlerOptions()

browser.mimeHandler.getMimeHandlerOptions(
  mimeType: string,
): Promise<MimeHandlerOptions>

MIME-এর প্রকারের জন্য বিকল্পগুলি পড়ে। প্রতিটি মেম্বার হল এক্সটেনশন সেটের ভ্যালু অথবা এক্সটেনশন সেট না করে থাকলে ম্যানিফেস্ট এন্ট্রির ভ্যালু।

প্যারামিটারগুলি

• mimeType

  স্ট্রিং

  MIME-এর ধরন যার বিকল্প পড়তে হবে। এটি অবশ্যই একটি MIME প্রকার হতে হবে যা এক্সটেনশন mime_types_handler-এর মাধ্যমে পরিচালনা করে।

রিটার্ন

• Promise<MimeHandlerOptions>

  MIME-এর প্রকারের বিকল্পের সাথে প্রমিস সমাধান করা হয়েছে।

getStreamInfo()

browser.mimeHandler.getStreamInfo(): Promise<StreamInfo>

বর্তমান MIME হ্যান্ডলার কনটেক্সটের জন্য স্ট্রিম সংক্রান্ত তথ্য ফিরিয়ে আনে। MIME হ্যান্ডলার এক্সটেনশন পৃষ্ঠা থেকে কল করতে হবে।

রিটার্ন

• Promise<StreamInfo>

setMimeHandlerOptions()

browser.mimeHandler.setMimeHandlerOptions(
  mimeType: string,
  options: MimeHandlerOptions,
): Promise<void>

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

প্যারামিটারগুলি

• mimeType

  স্ট্রিং

  কনফিগার করার জন্য MIME-এর ধরন। এটি অবশ্যই একটি MIME প্রকার হতে হবে যা এক্সটেনশন mime_types_handler-এর মাধ্যমে পরিচালনা করে।

• বিকল্প

  MimeHandlerOptions

  পরিবর্তন করার বিকল্প।

রিটার্ন

• <void> প্রমিস

  কনফিগারেশন সেট করা হয়ে গেলে প্রমিস রিজলভ করা হয়।