Mesajlaşma API'leri, uzantınızla ilişkili bağlamlarda çalışan farklı komut dosyaları arasında iletişim kurmanıza olanak tanır. Hizmet çalışanınız, chrome-extension://pages ve içerik komut dosyaları arasındaki iletişim de buna dahildir. Örneğin, bir RSS okuyucu uzantısı, bir sayfada RSS özet akışının varlığını algılamak için içerik komut dosyalarını kullanabilir ve ardından hizmet çalışanına bu sayfanın işlem simgesini güncellemesini bildirebilir.
İki mesaj iletme API'si vardır: Biri tek seferlik istekler için, diğeri ise birden fazla mesajın gönderilmesine olanak tanıyan uzun süreli bağlantılar için daha karmaşık bir API'dir.
Uzantılar arasında mesaj gönderme hakkında bilgi edinmek için uzantılar arası mesajlar bölümüne bakın.
Tek seferlik istekler
Uzantınızın başka bir bölümüne tek bir mesaj göndermek ve isteğe bağlı olarak yanıt almak için runtime.sendMessage() veya tabs.sendMessage() yöntemini çağırın.
Bu yöntemler, içerik komut dosyasından uzantıya veya uzantıdan içerik komut dosyasına tek seferlik JSON ile serileştirilebilir bir mesaj göndermenize olanak tanır. Her iki API de alıcı tarafından sağlanan yanıta çözümlenen bir Promise döndürür.
İçerik komut dosyasından istek gönderme işlemi şu şekilde görünür:
content-script.js:
(async () => {
const response = await browser.runtime.sendMessage({greeting: "hello"});
// do something with response here, not outside the function
console.log(response);
})();
Yanıtlar
Mesajları dinlemek için browser.runtime.onMessage etkinliğini kullanın:
// Event listener
function handleMessages(message, sender, sendResponse) {
if (message !== 'get-status') return;
fetch('https://example.com')
.then((response) => sendResponse({statusCode: response.status}))
// Since `fetch` is asynchronous, must return an explicit `true`
return true;
}
browser.runtime.onMessage.addListener(handleMessages);
// From the sender's context...
const {statusCode} = await browser.runtime.sendMessage('get-status');
Etkinlik işleyici çağrıldığında üçüncü parametre olarak bir sendResponse işlevi iletilir. Bu, yanıt vermek için çağrılabilecek bir işlevdir. Varsayılan olarak, sendResponse geri çağırma işlevi eşzamanlı olarak çağrılmalıdır.
sendResponse yöntemini herhangi bir parametre olmadan çağırırsanız yanıt olarak null gönderilir.
Eşzamansız olarak yanıt göndermek için iki seçeneğiniz vardır: true döndürme veya bir promise döndürme.
İade true
sendResponse() kullanarak eşzamansız olarak yanıt vermek için etkinlik işleyiciden gerçek bir true döndürün (yalnızca doğru bir değer değil). Böylece, sendResponse çağrılana kadar mesaj kanalı diğer uç için açık kalır ve daha sonra çağrı yapabilirsiniz.
Promise döndürme
Chrome 148'den itibaren, eşzamansız olarak yanıt vermek için bir mesaj dinleyiciden Promise döndürebilirsiniz. Bu güncelleme kademeli olarak kullanıma sunulduğundan henüz tüm kullanıcıların tarayıcılarında kullanılamayabilir. Uzantınızın bu özelliğin etkin olup olmadığını işleyebildiğinden emin olmanız gerekir. return true; kullanımı, bu özellik etkinleştirilmiş olsun veya olmasın eşzamansız yanıtlar için çalışmaya devam eder.
Promise çözümlenirse çözümlenen değeri yanıt olarak gönderilir.
Promise reddedilirse gönderenin sendMessage() çağrısı, hata mesajıyla birlikte reddedilir. Daha fazla bilgi ve örnek için hata işleme bölümüne bakın.
Aşağıdaki örnekte, çözümlenebilecek veya reddedilebilecek bir Promise döndürülmektedir:
// Event listener
function handleMessages(message, sender, sendResponse) {
// Return a promise that wraps fetch
// If the response is OK, resolve with the status. If it's not OK then reject
// with the network error that prevents the fetch from completing.
return new Promise((resolve, reject) => {
fetch('https://example.com')
.then(response => {
if (!response.ok) {
reject(response);
} else {
resolve(response.status);
}
})
.catch(error => {
reject(error);
});
});
}
browser.runtime.onMessage.addListener(handleMessages);
Bir dinleyiciyi, bir söz döndürmek için async olarak da tanımlayabilirsiniz:
browser.runtime.onMessage.addListener(async function(message, sender) {
const response = await fetch('https://example.com');
if (!response.ok) {
// rejects the promise returned by `async function`.
throw new Error(`Fetch failed: ${response.status}`);
}
// resolves the promise returned by `async function`.
return {statusCode: response.status};
});
Promise döndürme: async işleviyle ilgili dikkat edilmesi gerekenler
Dinleyici olarak bir async işlevinin, return ifadesi olmasa bile her zaman bir promise döndüreceğini unutmayın. Bir async dinleyicisi değer döndürmezse vaadi dolaylı olarak undefined değerine çözümlenir ve gönderene yanıt olarak null gönderilir. Bu durum, birden fazla dinleyici olduğunda beklenmeyen davranışlara neden olabilir:
// content_script.js
function handleResponse(message) {
// The first listener promise resolves to `undefined` before the second
// listener can respond. When a listener responds with `undefined`, Chrome
// sends null as the response.
console.assert(message === null);
}
function notifyBackgroundPage() {
const sending = browser.runtime.sendMessage('test');
sending.then(handleResponse);
}
notifyBackgroundPage();
// background.js
browser.runtime.onMessage.addListener(async (message) => {
// This just causes the function to pause for a millisecond, but the promise
// is *not* returned from the listener so it doesn't act as a response.
await new Promise(resolve => {
setTimeout(resolve, 1, 'OK');
});
// `async` functions always return promises. So once we
// reach here there is an implicit `return undefined;`. Chrome translates
// `undefined` responses to `null`.
});
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
return new Promise((resolve) => {
setTimeout(resolve, 1000, 'response');
});
});
Hata işleme
Chrome 146'dan itibaren, bir onMessage dinleyicisi hata verirse (eşzamanlı olarak veya reddeden bir söz döndürerek eşzamansız olarak), gönderendeki sendMessage() tarafından döndürülen söz, hatanın mesajıyla birlikte reddedilir. Bu güncelleme kademeli olarak kullanıma sunulduğundan, bu değişikliğin henüz tüm kullanıcıların tarayıcılarında geçerli olmadığını görebilirsiniz. Uzantınızın bu değişikliğin etkin olup olmadığını
işleyebildiğinden emin olmanız gerekir.
Bir dinleyici, serileştirilemeyen bir yanıt döndürmeye çalışırsa (ortaya çıkan TypeError yakalanmadan) bu da dinleyicinin hata vermesi olarak kabul edilir.
Bir dinleyici, reddeden bir promise döndürürse gönderenin bu hata mesajını alması için bir Error örneğiyle reddetmesi gerekir. Promise başka bir değerle (ör. null veya undefined) reddedilirse sendMessage() bunun yerine genel bir hata mesajıyla reddedilir.
onMessage için birden fazla işleyici kayıtlıysa yalnızca yanıt veren, reddeden veya hata veren ilk işleyici göndereni etkiler. Diğer tüm işleyiciler çalıştırılır ancak sonuçları yok sayılır.
Örnekler
Bir dinleyici, reddeden bir promise döndürürse sendMessage() reddedilir:
// sender.js
try {
await browser.runtime.sendMessage('test');
} catch (e) {
console.log(e.message); // "some error"
}
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
return Promise.reject(new Error('some error'));
});
Bir dinleyici, serileştirilemeyen bir değerle yanıt verirse sendMessage() reddedilir:
// sender.js
try {
await browser.runtime.sendMessage('test');
} catch (e) {
console.log(e.message); // "Error: Could not serialize message."
}
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
sendResponse(() => {}); // Functions are not serializable
return true; // Keep channel open for async sendResponse
});
Bir dinleyici, başka bir dinleyici yanıt vermeden önce eşzamanlı olarak hata verirse dinleyicinin sendMessage() vaadi reddedilir:
// sender.js
try {
await browser.runtime.sendMessage('test');
} catch (e) {
console.log(e.message); // "error!"
}
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
throw new Error('error!');
});
Ancak bir dinleyici, başka bir dinleyici hata vermeden önce yanıt verirse sendMessage() başarılı olur:
// sender.js
const response = await browser.runtime.sendMessage('test');
console.log(response); // "OK"
// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
sendResponse('OK');
});
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
throw new Error('error!');
});
Uzun süreli bağlantılar
Yeniden kullanılabilir, uzun ömürlü bir mesaj iletme kanalı oluşturmak için şunu çağırın:
- İçerik komut dosyasından uzantı sayfasına mesaj iletmek için
runtime.connect() - Uzantı sayfasından içerik komut dosyasına mesaj iletmek için
tabs.connect().
Farklı bağlantı türlerini ayırt etmek için name anahtarı içeren bir seçenekler parametresi ileterek kanalınızı adlandırabilirsiniz:
const port = browser.runtime.connect({name: "example"});
Uzun süreli bağlantının olası kullanım alanlarından biri, otomatik form doldurma uzantısıdır. İçerik komut dosyası, belirli bir giriş için uzantı sayfasına bir kanal açabilir ve sayfadaki her giriş öğesi için uzantıya bir mesaj göndererek doldurulacak form verilerini isteyebilir. Paylaşılan bağlantı, uzantının uzantı bileşenleri arasında durum paylaşmasına olanak tanır.
Bağlantı kurulurken her uca, bu bağlantı üzerinden mesaj gönderip almak için bir runtime.Port nesnesi atanır.
İçerik komut dosyasından kanal açmak, mesaj göndermek ve mesajları dinlemek için aşağıdaki kodu kullanın:
content-script.js:
const port = browser.runtime.connect({name: "knockknock"});
port.onMessage.addListener(function(msg) {
if (msg.question === "Who's there?") {
port.postMessage({answer: "Madame"});
} else if (msg.question === "Madame who?") {
port.postMessage({answer: "Madame... Bovary"});
}
});
port.postMessage({joke: "Knock knock"});
Uzantıdan bir içerik komut dosyasına istek göndermek için önceki örnekteki runtime.connect() çağrısını tabs.connect() ile değiştirin.
Bir içerik komut dosyası veya uzantı sayfası için gelen bağlantıları işlemek üzere bir runtime.onConnect etkinlik işleyici oluşturun. Uzantınızın başka bir bölümü connect() yöntemini çağırdığında bu etkinlik ve runtime.Port nesnesi etkinleştirilir. Gelen bağlantılara yanıt verme kodu aşağıdaki gibidir:
service-worker.js:
browser.runtime.onConnect.addListener(function(port) {
if (port.name !== "knockknock") {
return;
}
port.onMessage.addListener(function(msg) {
if (msg.joke === "Knock knock") {
port.postMessage({question: "Who's there?"});
} else if (msg.answer === "Madame") {
port.postMessage({question: "Madame who?"});
} else if (msg.answer === "Madame... Bovary") {
port.postMessage({question: "I don't get it."});
}
});
});
Serileştirme
Chrome'da mesaj ileten API'ler JSON serileştirme kullanır. Bu, aynı API'leri yapılandırılmış klon algoritmasıyla uygulayan diğer tarayıcılardan farklıdır.
Bu, bir mesajın (ve alıcılar tarafından sağlanan yanıtların) geçerli herhangi bir JSON.stringify() değeri içerebileceği anlamına gelir. Diğer değerler, serileştirilebilir değerlere dönüştürülür (özellikle undefined, null olarak serileştirilir).
İleti boyutu sınırları
Bir mesajın maksimum boyutu 64 MiB'dir.
Bağlantı noktası ömrü
Bağlantı noktaları, bir uzantının farklı bölümleri arasında iki yönlü bir iletişim mekanizması olarak tasarlanmıştır. Bir uzantının parçası tabs.connect(), runtime.connect() veya runtime.connectNative() yöntemini çağırdığında, postMessage() kullanarak hemen mesaj gönderebilen bir Port oluşturur.
Bir sekmede birden fazla çerçeve varsa tabs.connect() çağrıldığında sekmedeki her çerçeve için runtime.onConnect etkinliği bir kez çağrılır. Benzer şekilde, runtime.connect() çağrılırsa onConnect etkinliği, uzantı işlemindeki her kare için bir kez tetiklenebilir.
Örneğin, her açık bağlantı noktası için ayrı durumlar kullanıyorsanız bir bağlantının ne zaman kapatıldığını öğrenmek isteyebilirsiniz. Bunun için runtime.Port.onDisconnect etkinliğini dinleyin. Bu etkinlik, kanalın diğer ucunda geçerli bağlantı noktası olmadığında tetiklenir. Bunun nedenleri şunlar olabilir:
- Diğer uçta
runtime.onConnectiçin dinleyici yok. - Bağlantı noktasını içeren sekme kaldırılırsa (ör. sekmede gezinilirse)
connect()işlevinin çağrıldığı çerçeve kaldırıldı.- Bağlantı noktasını alan tüm çerçeveler (
runtime.onConnectaracılığıyla) kaldırıldı. runtime.Port.disconnect(), karşı taraf tarafından aranır. Birconnect()çağrısı, alıcı tarafında birden fazla bağlantı noktasıyla sonuçlanırsa ve bu bağlantı noktalarından herhangi birindedisconnect()çağrılırsaonDisconnectetkinliği yalnızca gönderen bağlantı noktasında tetiklenir, diğer bağlantı noktalarında tetiklenmez.
Uzantılar arası mesajlaşma
Uzantınızdaki farklı bileşenler arasında mesaj göndermenin yanı sıra diğer uzantılarla iletişim kurmak için mesajlaşma API'sini kullanabilirsiniz. Bu sayede, diğer uzantıların kullanabileceği herkese açık bir API sunabilirsiniz.
Diğer uzantılardan gelen istekleri ve bağlantıları dinlemek için runtime.onMessageExternal veya runtime.onConnectExternal yöntemlerini kullanın. Her birine bir örnek verelim:
service-worker.js
// For a single request:
browser.runtime.onMessageExternal.addListener(
function(request, sender, sendResponse) {
if (sender.id !== allowlistedExtension) {
return; // don't allow this extension access
}
if (request.getTargetData) {
sendResponse({ targetData: targetData });
} else if (request.activateLasers) {
const success = activateLasers();
sendResponse({ activateLasers: success });
}
}
);
// For long-lived connections:
browser.runtime.onConnectExternal.addListener(function(port) {
port.onMessage.addListener(function(msg) {
// See other examples for sample onMessage handlers.
});
});
Başka bir uzantıya mesaj göndermek için iletişim kurmak istediğiniz uzantının kimliğini aşağıdaki gibi iletin:
service-worker.js
// The ID of the extension we want to talk to.
const laserExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";
// For a minimal request:
browser.runtime.sendMessage(laserExtensionId, {getTargetData: true},
function(response) {
if (targetInRange(response.targetData))
browser.runtime.sendMessage(laserExtensionId, {activateLasers: true});
}
);
// For a long-lived connection:
const port = browser.runtime.connect(laserExtensionId);
port.postMessage(...);
Web sayfalarından mesaj gönderme
Uzantılar, web sayfalarından mesaj alabilir ve bu mesajlara yanıt verebilir. Bir web sayfasından uzantıya mesaj göndermek için "externally_connectable" manifest anahtarını kullanarak manifest.json dosyanızda hangi web sitelerinden mesajlara izin vermek istediğinizi belirtin. Örneğin:
manifest.json
"externally_connectable": {
"matches": ["https://*.example.com/*"]
}
Bu, mesajlaşma API'sini belirttiğiniz eşleşme kalıplarıyla eşleşen tüm sayfalara gösterir.
Belirli bir uzantıya mesaj göndermek için runtime.sendMessage() veya runtime.connect() API'lerini kullanın. Örneğin:
webpage.js
// The ID of the extension we want to talk to.
const editorExtensionId = 'abcdefghijklmnoabcdefhijklmnoabc';
// Check if extension is installed
if (chrome && browser.runtime) {
// Make a request:
browser.runtime.sendMessage(
editorExtensionId,
{
openUrlInEditor: url
},
(response) => {
if (!response.success) handleError(url);
}
);
}
Uzantınızdan, uzantılar arası mesajlaşmada olduğu gibi runtime.onMessageExternal veya runtime.onConnectExternal API'lerini kullanarak web sayfalarından gelen mesajları dinleyin. Aşağıda bununla ilgili bir örnek verilmiştir:
service-worker.js
browser.runtime.onMessageExternal.addListener(
function(request, sender, sendResponse) {
if (sender.url === blocklistedWebsite)
return; // don't allow this web page access
if (request.openUrlInEditor)
openUrl(request.openUrlInEditor);
});
Uzantıdan web sayfasına mesaj göndermek mümkün değildir.
Yerel mesajlaşma
Uzantılar, yerel mesajlaşma ana makinesi olarak kayıtlı yerel uygulamalarla mesaj alışverişi yapabilir. Bu özellik hakkında daha fazla bilgi edinmek için Yerel mesajlaşma başlıklı makaleyi inceleyin.
Güvenlikle ilgili olarak göz önünde bulundurulması gerekenler
Mesajlaşmayla ilgili birkaç güvenlik hususu aşağıda verilmiştir.
İçerik komut dosyaları daha az güvenilirdir
İçerik komut dosyaları, uzantı hizmet çalışanından daha az güvenilirdir. Örneğin, kötü amaçlı bir web sayfası, içerik komut dosyalarını çalıştıran oluşturma işlemini tehlikeye atabilir. İçerik komut dosyasından gelen mesajların bir saldırgan tarafından hazırlanmış olabileceğini varsayın ve tüm girişleri doğrulayıp temizlediğinizden emin olun. İçerik komut dosyasına gönderilen tüm verilerin web sayfasına sızabileceğini varsayın. İçerik komut dosyalarından alınan mesajlarla tetiklenebilecek ayrıcalıklı işlemlerin kapsamını sınırlayın.
Siteler arası komut dosyası çalıştırma
Komut dosyalarınızı siteler arası komut dosyası çalıştırmaya karşı koruduğunuzdan emin olun. Kullanıcı girişi, içerik komut dosyası aracılığıyla diğer web siteleri veya API gibi güvenilmeyen bir kaynaktan veri alırken bunu HTML olarak yorumlamamaya veya beklenmedik kodların çalıştırılmasına izin verebilecek şekilde kullanmamaya dikkat edin.
Mümkün olduğunda komut dosyası çalıştırmayan API'leri kullanın:
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // JSON.parse doesn't evaluate the attacker's scripts. const resp = JSON.parse(response.farewell); });
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // innerText does not let the attacker inject HTML elements. document.getElementById("resp").innerText = response.farewell; });
Uzantınızı güvenlik açıklarına karşı savunmasız hale getiren aşağıdaki yöntemleri kullanmaktan kaçının:
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // WARNING! Might be evaluating a malicious script! const resp = eval(`(${response.farewell})`); });
service-worker.js
browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) { // WARNING! Might be injecting a malicious script! document.getElementById("resp").innerHTML = response.farewell; });