Manifest V3, uzantıların ağ isteklerinin değiştirilmesini nasıl ele aldığını değiştirir. Uzantınız, ağ isteklerini yakalayıp çalışma zamanında chrome.webRequest ile değiştirmek yerine, belirli bir koşul grubu karşılandığında gerçekleştirilecek işlemleri açıklayan kurallar belirtir. Bu işlemi Bildirimsel Ağ İsteği API'sini kullanarak yapın.
Web Request API ile Declarative Net Request API'leri arasında önemli farklar vardır. Bir işlev çağrısını diğeriyle değiştirmek yerine kodunuzu kullanım alanlarına göre yeniden yazmanız gerekir. Bu bölümde, söz konusu süreç adım adım açıklanmaktadır.
Uzantınız politika aracılığıyla yüklenmişse bu değişiklikleri yapmanız gerekmez. Politikayla yüklenen uzantılar için webRequestBlocking izni, Manifest V3'te kullanılmaya devam edecektir.
Bu bölüm, uzantı hizmet çalışanı kapsamında olmayan kod için gereken değişiklikleri açıklayan üç bölümden ikincisidir. Manifest V2 tarafından kullanılan engelleme web isteklerinin, Manifest V3 tarafından kullanılan bildirimli ağ isteklerine dönüştürülmesi açıklanmaktadır. Diğer iki bölümde ise Manifest V3'e geçiş için gereken kodunuzu güncelleme ve güvenliği iyileştirme konuları ele alınmaktadır.
Giriş
Manifest V2'de web isteklerinin engellenmesi hem uzantıların hem de çalıştıkları sayfaların performansını önemli ölçüde düşürebiliyordu. webRequest ad alanı, her biri sınırsız sayıda etkinlik işleyici alan dokuz olası engelleme etkinliğini destekler. Daha da kötüsü, her web sayfası birden fazla uzantı tarafından engellenebilir ve bunun için gereken izinler müdahaleci niteliktedir. Manifest V3, geri çağırmaları bildirim temelli kurallarla değiştirerek bu soruna karşı koruma sağlar.
İzinleri güncelle
manifest.json dosyanızdaki "permissions" alanında aşağıdaki değişiklikleri yapın.
- Ağ isteklerini izlemeniz gerekmiyorsa
"webRequest"iznini kaldırın. - Eşleme kalıplarını
"permissions"kampanyasından"host_permissions"kampanyasına taşıyın.
Kullanım alanınıza bağlı olarak başka izinler de eklemeniz gerekir. Bu izinler, destekledikleri kullanım alanıyla birlikte açıklanır.
Bildirimsel ağ isteği kuralları oluşturma
Bildirimli ağ isteği kuralları oluşturmak için "declarative_net_request" öğenize bir manifest.json nesnesi eklemeniz gerekir. "declarative_net_request" bloğu, bir kural dosyasına işaret eden bir "rule_resource" nesneleri dizisi içerir. Kural dosyası, bir işlemi ve bu işlemlerin çağrıldığı koşulları belirten bir nesne dizisi içerir.
Yaygın kullanım örnekleri
Aşağıdaki bölümlerde, bildirim temelli ağ istekleriyle ilgili yaygın kullanım alanları açıklanmaktadır. Aşağıdaki talimatlar yalnızca kısa bir özet sunmaktadır. Buradaki tüm bilgiler hakkında daha fazla bilgiyi chrome.declarativeNetRequest bölümündeki API referansında bulabilirsiniz.
Tek bir URL'yi engelleme
Manifest V2'de yaygın bir kullanım alanı, arka plan komut dosyasındaki onBeforeRequest etkinliğini kullanarak web isteklerini engellemekti.
chrome.webRequest.onBeforeRequest.addListener((e) => { return { cancel: true }; }, { urls: ["https://www.example.com/*"] }, ["blocking"]);
Manifest V3 için "block" işlem türünü kullanarak yeni bir declarativeNetRequest kuralı oluşturun. Örnek kuraldaki "condition" nesnesine dikkat edin. "urlFilter", webRequest dinleyicisine iletilen urls seçeneğinin yerini alır. "resourceTypes" dizisi, engellenecek kaynak kategorisini belirtir. Bu örnekte yalnızca ana HTML sayfası engellenir. Ancak örneğin yalnızca yazı tiplerini de engelleyebilirsiniz.
[ { "id" : 1, "priority": 1, "action" : { "type" : "block" }, "condition" : { "urlFilter" : "||example.com", "resourceTypes" : ["main_frame"] } } ]
Bu özelliği kullanmak için uzantının izinlerini güncellemeniz gerekir. manifest.json bölümünde "webRequestBlocking" iznini "declarativeNetRequest" izniyle değiştirin. İçeriğin engellenmesi için ana bilgisayar izinleri gerekmediğinden URL'nin "permissions" alanından kaldırıldığını unutmayın. Yukarıda gösterildiği gibi, kural dosyası, bildirimli bir ağ isteğinin uygulandığı ana makineyi veya ana makineleri belirtir.
Bu özelliği denemek isterseniz aşağıdaki kodu örnekler depomuzda bulabilirsiniz.
"permissions": [ "webRequestBlocking", "https://*.example.com/*" ]
"permissions": [ "declarativeNetRequest", ]
Birden çok URL'yi yönlendirme
Manifest V2'deki bir diğer yaygın kullanım alanı da web isteklerini yönlendirmek için BeforeRequest etkinliğini kullanmaktı.
chrome.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"] );
Manifest V3 için "redirect" işlem türünü kullanın. Daha önce olduğu gibi, "urlFilter", webRequest dinleyicisine iletilen url seçeneğinin yerini alır. Bu örnekte, kural dosyasının "action" nesnesinin, filtrelenen URL yerine döndürülecek URL'yi içeren bir "redirect" alanı içerdiğini unutmayın.
[ { "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"] } } ]
Bu senaryo, uzantının izinlerinde de değişiklik yapılmasını gerektirir. Daha önce olduğu gibi, "webRequestBlocking" iznini "declarativeNetRequest" izniyle değiştirin. URL'ler tekrar manifest.json klasöründen bir kural dosyasına taşınır. Yönlendirme için ana makine izninin yanı sıra "declarativeNetRequestWithHostAccess" izninin de gerektiğini unutmayın.
Bu özelliği denemek isterseniz aşağıdaki kodu örnekler depomuzda bulabilirsiniz.
"permissions": [ "webRequestBlocking", "https://developer.chrome.com/docs/extensions/*", "https://developer.chrome.com/docs/extensions/reference" ]
"permissions": [ "declarativeNetRequestWithHostAccess" ], "host_permissions": [ "https://developer.chrome.com/*" ]
Çerezleri engelleme
Manifest V2'de çerezlerin engellenmesi için web isteği başlıklarının gönderilmeden önce yakalanması ve belirli bir başlığın kaldırılması gerekir.
chrome.webRequest.onBeforeSendHeaders.addListener( function(details) { removeHeader(details.requestHeaders, 'cookie'); return {requestHeaders: details.requestHeaders}; }, // filters {urls: ['https://*/*', 'http://*/*']}, // extraInfoSpec ['blocking', 'requestHeaders', 'extraHeaders']);
Manifest V3 de bunu bir kural dosyasındaki kural aracılığıyla yapar. Bu kez işlem türü "modifyHeaders". Dosya, değiştirilecek üstbilgileri ve bunların nasıl değiştirileceğini belirten bir "requestHeaders" nesne dizisi alır. "condition" nesnesinin yalnızca bir "resourceTypes" dizisi içerdiğini unutmayın. Önceki örneklerle aynı değerleri destekler.
Bu özelliği denemek isterseniz aşağıdaki kodu örnekler depomuzda bulabilirsiniz.
[ { "id": 1, "priority": 1, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "cookie", "operation": "remove" } ] }, "condition": { "urlFilter": "|*?no-cookies=1", "resourceTypes": ["main_frame"] } } ]
Bu senaryo, uzantının izinlerinde de değişiklik yapılmasını gerektirir. Daha önce olduğu gibi, "webRequestBlocking" iznini "declarativeNetRequest" izniyle değiştirin.
"permissions": [ "webRequest", "webRequestBlocking", "https://*/*", "http://*/*" ],
"permissions": [ "declarativeNetRequest", ], "host_permissions": [ "" ]