Ganti pemroses permintaan web pemblokiran

Manifes V3 mengubah cara ekstensi menangani modifikasi permintaan jaringan. Daripada mencegat permintaan jaringan dan mengubahnya saat runtime dengan browser.webRequest, ekstensi Anda menentukan aturan yang menjelaskan tindakan yang akan dilakukan saat serangkaian kondisi tertentu terpenuhi. Lakukan ini menggunakan Declarative Net Request API.

Web Request API dan Declarative Net Request API sangat berbeda. Daripada mengganti satu panggilan fungsi dengan panggilan fungsi lain, Anda perlu menulis ulang kode dalam hal kasus penggunaan. Bagian ini akan memandu Anda menjalani proses tersebut.

Anda tidak perlu melakukan perubahan ini jika ekstensi Anda diinstal oleh kebijakan. Untuk ekstensi yang diinstal kebijakan, izin webRequestBlocking masih tersedia di Manifes V3.

Ini adalah bagian kedua dari tiga bagian yang menjelaskan perubahan yang diperlukan untuk kode yang bukan bagian dari service worker ekstensi. Bagian ini menjelaskan cara mengonversi permintaan web yang memblokir, yang digunakan oleh Manifest V2, menjadi permintaan bersih deklaratif, yang digunakan oleh Manifest V3. Dua bagian lainnya membahas mengupdate kode yang diperlukan untuk bermigrasi ke Manifes V3 dan meningkatkan keamanan.

Pengantar

Di Manifest V2, memblokir permintaan web dapat menurunkan performa ekstensi dan performa halaman yang berinteraksi dengan ekstensi tersebut secara signifikan. Namespace webRequest mendukung sembilan peristiwa yang berpotensi memblokir, yang masing-masing mengambil jumlah handler peristiwa yang tidak terbatas. Lebih buruk lagi, setiap halaman web berpotensi diblokir oleh beberapa ekstensi, dan izin yang diperlukan untuk hal ini bersifat invasif. Manifest V3 mencegah masalah ini dengan mengganti callback dengan aturan deklaratif.

Perbarui izin

Buat perubahan berikut pada kolom "permissions" di manifest.json Anda.

  • Hapus izin "webRequest" jika Anda tidak lagi perlu mengamati permintaan jaringan.
  • Memindahkan Pola Pencocokan dari "permissions" ke "host_permissions".

Anda harus menambahkan izin lain, bergantung pada kasus penggunaan Anda. Izin tersebut dijelaskan dengan kasus penggunaan yang didukungnya.

Membuat aturan permintaan jaringan deklaratif

Membuat aturan permintaan bersih deklaratif memerlukan penambahan objek "declarative_net_request" ke manifest.json Anda. Blok "declarative_net_request" berisi array objek "rule_resource" yang mengarah ke file aturan. File aturan berisi array objek yang menentukan tindakan dan kondisi saat tindakan tersebut dipanggil.

Kasus penggunaan umum

Bagian berikut menjelaskan kasus penggunaan umum untuk permintaan bersih deklaratif. Petunjuk di bawah hanya memberikan garis besar singkat. Informasi selengkapnya tentang semua informasi di sini dijelaskan dalam referensi API di bagian browser.declarativeNetRequest

Memblokir satu URL

Kasus penggunaan umum di Manifest V2 adalah memblokir permintaan web menggunakan peristiwa onBeforeRequest dalam skrip latar belakang.

Skrip latar belakang Manifest V2
browser.webRequest.onBeforeRequest.addListener((e) => {
    return { cancel: true };
}, { urls: ["https://www.example.com/*"] }, ["blocking"]);

Untuk Manifes V3, buat aturan declarativeNetRequest baru menggunakan jenis tindakan "block". Perhatikan objek "condition" dalam contoh aturan. "urlFilter"-nya menggantikan opsi urls yang diteruskan ke pemroses webRequest. Array "resourceTypes" menentukan kategori resource yang akan diblokir. Contoh ini hanya memblokir halaman HTML utama, tetapi Anda dapat, misalnya, hanya memblokir font.

File aturan Manifest V3
[
  {
    "id" : 1,
    "priority": 1,
    "action" : { "type" : "block" },
    "condition" : {
      "urlFilter" : "||example.com",
      "resourceTypes" : ["main_frame"]
    }
  }
]

Agar dapat berfungsi, Anda harus memperbarui izin ekstensi. Di manifest.json, ganti izin "webRequestBlocking" dengan izin "declarativeNetRequest". Perhatikan bahwa URL dihapus dari kolom "permissions" karena pemblokiran konten tidak memerlukan izin host. Seperti yang ditunjukkan di atas, file aturan menentukan host yang akan diterapkan permintaan bersih deklaratif.

Jika Anda ingin mencobanya, kode di bawah tersedia di repo contoh kami.

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://*.example.com/*"
  ]
Manifes V3
  "permissions": [
    "declarativeNetRequest",
  ]

Mengalihkan beberapa URL

Kasus penggunaan umum lainnya di Manifes V2 adalah menggunakan peristiwa BeforeRequest untuk mengalihkan permintaan web.

Skrip latar belakang Manifest V2
browser.webRequest.onBeforeRequest.addListener((e) => {
    console.log(e);
    return { redirectUrl: "https://developer.chrome.com/docs/extensions/mv3/intro/" };
  }, { 
    urls: [
      "https://developer.chrome.com/docs/extensions/mv2/"
    ]
  }, 
  ["blocking"]
);

Untuk Manifest V3, gunakan jenis tindakan "redirect". Seperti sebelumnya, "urlFilter" menggantikan opsi url yang diteruskan ke pemroses webRequest. Perhatikan bahwa untuk contoh ini, objek "action" file aturan berisi kolom "redirect" yang berisi URL yang akan ditampilkan, bukan URL yang difilter.

File aturan Manifest V3
[
  {
    "id" : 1,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": { "url": "https://developer.chrome.com/docs/extensions/mv3/intro/" }
    },
    "condition": {
      "urlFilter": "https://developer.chrome.com/docs/extensions/mv2/",
      "resourceTypes": ["main_frame"]
    }
  }
]

Skenario ini juga memerlukan perubahan pada izin ekstensi. Seperti sebelumnya, ganti izin "webRequestBlocking" dengan izin "declarativeNetRequest". URL dipindahkan lagi dari manifest.json ke file aturan. Perhatikan bahwa pengalihan juga memerlukan izin "declarativeNetRequestWithHostAccess" selain izin host.

Jika Anda ingin mencobanya, kode di bawah tersedia di repo contoh kami.

Manifest V2
  "permissions": [
    "webRequestBlocking",
    "https://developer.chrome.com/docs/extensions/*",
    "https://developer.chrome.com/docs/extensions/reference"
  ]
Manifes V3
  "permissions": [
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]

Memblokir cookie

Di Manifest V2, pemblokiran cookie memerlukan pencegatan header permintaan web sebelum dikirim dan penghapusan cookie tertentu.

Skrip latar belakang Manifest V2
browser.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    removeHeader(details.requestHeaders, 'cookie');
    return {requestHeaders: details.requestHeaders};
  },
  // filters
  {urls: ['https://*/*', 'http://*/*']},
  // extraInfoSpec
  ['blocking', 'requestHeaders', 'extraHeaders']);

Manifest V3 juga melakukannya dengan aturan dalam file aturan. Kali ini, jenis tindakan adalah "modifyHeaders". File ini mengambil array objek "requestHeaders" yang menentukan header yang akan diubah dan cara mengubahnya. Perhatikan bahwa objek "condition" hanya berisi array "resourceTypes". Kode ini mendukung nilai yang sama seperti contoh sebelumnya.

Jika Anda ingin mencobanya, kode di bawah tersedia di repo contoh kami.

manifest.json Manifest V3
[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "cookie", "operation": "remove" }
      ]
    },
    "condition": {
      "urlFilter": "|*?no-cookies=1",
      "resourceTypes": ["main_frame"]
    }
  }
]

Skenario ini juga memerlukan perubahan pada izin ekstensi. Seperti sebelumnya, ganti izin "webRequestBlocking" dengan izin "declarativeNetRequest".

Manifest V2
  "permissions": [
    "webRequest",
    "webRequestBlocking",
    "https://*/*",
    "http://*/*"
  ],
Manifes V3
  "permissions": [
    "declarativeNetRequest",
  ],
  "host_permissions": [
    ""
  ]