chrome.runtime

Açıklama

Hizmet işçisini almak, manifest ile ilgili ayrıntıları döndürmek ve uzantı yaşam döngüsündeki etkinlikleri dinleyip yanıtlamak için chrome.runtime API'yi kullanın. URL'lerin göreceli yolunu tam nitelikli URL'lere dönüştürmek için de bu API'yi kullanabilirsiniz.

Bu API'nin çoğu üyesi herhangi bir izin istemez. Bu izin, connectNative(), sendNativeMessage() ve onNativeConnect için gereklidir.

Aşağıdaki örnekte, "nativeMessaging" izninin manifest dosyasında nasıl tanımlanacağı gösterilmektedir:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Kavramlar ve kullanım

Runtime API, uzantılarınızın kullanabileceği çeşitli alanları destekleyen yöntemler sağlar:

Mesaj aktarımı

Uzantınız, şu yöntemleri ve etkinlikleri kullanarak kendi içindeki farklı bağlamlarla ve diğer uzantılarla iletişim kurabilir: connect(), onConnect, onConnectExternal, sendMessage(), onMessage ve onMessageExternal. Ayrıca uzantınız, connectNative() ve sendNativeMessage() kullanarak kullanıcının cihazındaki yerel uygulamalara mesaj iletebilir.

Not: Konuya genel bakış için Mesaj İletimi bölümüne bakın.

Uzantı ve platform meta verilerine erişme

Bu yöntemler, uzantı ve platformla ilgili belirli meta veri parçalarını almanıza olanak tanır. Bu kategorideki yöntemler arasında getManifest() ve getPlatformInfo() yer alır.

Uzantı yaşam döngüsünü ve seçeneklerini yönetme

Bu mülkler, uzantı üzerinde bazı meta işlemleri gerçekleştirmenize ve seçenekler sayfasını görüntülemenize olanak tanır. Bu kategorideki yöntemler ve etkinlikler arasında onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() ve setUninstallURL() yer alır.

Yardımcı programlar

Bu yöntemler, dahili kaynak gösterimlerinin harici biçimlere dönüştürülmesi gibi faydalar sağlar. Bu kategorideki yöntemler arasında getURL() yer alır.

Kiosk modu yardımcı programları

Bu yöntemler yalnızca ChromeOS'te kullanılabilir ve temel olarak kiosk uygulamalarını desteklemek için mevcuttur. Bu kategorideki yöntemler arasında restart() ve restartAfterDelay()` yer alır.

Ayıklanmış uzantı davranışı

Ayıklanmış bir uzantı yeniden yüklendiğinde bu işlem güncelleme olarak kabul edilir. Bu, chrome.runtime.onInstalled etkinliğinin "update" nedeniyle tetikleneceği anlamına gelir. Buna, uzantının chrome.runtime.reload() ile yeniden yüklenmesi de dahildir.

Kullanım alanları

Web sayfasına resim ekleme

Bir web sayfasının başka bir alanda barındırılan bir öğeye erişebilmesi için kaynağın tam URL'sini (ör. <img src="https://example.com/logo.png">) belirtmesi gerekir. Web sayfasına uzantı öğesi eklemek için de aynı durum geçerlidir. Bu iki farkın birincisi, uzantının öğelerinin web'den erişilebilir kaynaklar olarak gösterilmesi, ikincisi ise genellikle uzantı öğelerinin yerleştirilmesinden içerik komut dosyalarının sorumlu olmasıdır.

Bu örnekte uzantı, tam nitelikli bir URL oluşturmak için runtime.getURL()'i kullanarak içerik komut dosyasının enjekte edildiği sayfaya logo.png ekler. Ancak önce öğenin manifest dosyasında web'e erişilebilir bir kaynak olarak tanımlanması gerekir.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

İçerik komut dosyasından hizmet işleyiciye veri gönderme

Bir uzantının içerik komut dosyalarının, uzantının başka bir parçası (ör. hizmet çalışanı) tarafından yönetilen verilere ihtiyaç duyması yaygındır. Aynı web sayfasına açılan iki tarayıcı penceresine benzer şekilde, bu iki bağlam birbirinin değerlerine doğrudan erişemez. Bunun yerine uzantı, bu farklı bağlamlarda koordinasyon sağlamak için mesaj aktarımı kullanabilir.

Bu örnekte, içerik komut dosyasının kullanıcı arayüzünü başlatmak için uzantının hizmet işleyicisinden bazı verilere ihtiyacı vardır. Bu verileri almak için geliştirici tarafından tanımlanan get-user-data mesajını servis işleyiciye iletir ve kullanıcı bilgilerinin bir kopyasıyla yanıt verir.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Kaldırmayla ilgili geri bildirim toplama

Birçok uzantı, kullanıcılarına nasıl daha iyi hizmet verebileceğini ve elde tutma oranını nasıl artırabileceğini anlamak için kaldırma sonrası anketler kullanır. Aşağıdaki örnekte bu işlevin nasıl ekleneceği gösterilmektedir.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Örnekler

Daha fazla çalışma zamanı API örneği için Manifest V3 - Web'e Erişimli Kaynaklar demosuna bakın.

Türler

ContextFilter

Chrome 114 ve sonraki sürümler

Belirli uzantı bağlamlarıyla eşleşecek bir filtre. Eşleşen bağlamlar, belirtilen tüm filtrelerle eşleşmelidir. Belirtilmeyen tüm filtreler, mevcut tüm bağlamlarla eşleşir. Bu nedenle, "{}" şeklinde bir filtre, mevcut tüm bağlamlarla eşleşir.

Özellikler

• contextIds

  string[] isteğe bağlı

• contextTypes

  ContextType[] isteğe bağlı

• documentIds

  string[] isteğe bağlı

• documentOrigins

  string[] isteğe bağlı

• documentUrls

  string[] isteğe bağlı

• frameIds

  number[] isteğe bağlı

• gizli

  boole isteğe bağlı

• tabIds

  number[] isteğe bağlı

• windowIds

  number[] isteğe bağlı

ContextType

Chrome 114 ve sonraki sürümler

Enum

"TAB"
Bağlam türünü sekme olarak belirtir

"POPUP"
Bağlam türünü uzantı pop-up penceresi olarak belirtir

"BACKGROUND"
Bağlam türünü hizmet çalışanı olarak belirtir.

"OFFSCREEN_DOCUMENT"
Bağlam türünü ekran dışı doküman olarak belirtir.

"SIDE_PANEL"
Bağlam türünü yan panel olarak belirtir.

"DEVELOPER_TOOLS"
Bağlam türünü geliştirici araçları olarak belirtir.

ExtensionContext

Chrome 114 ve sonraki sürümler

Uzantı içeriğini barındıran bir bağlam.

Özellikler

• contextId

  dize

  Bu bağlam için benzersiz bir tanımlayıcı

• contextType

  ContextType

  Bu bağlama karşılık gelen tür.

• documentId

  dize isteğe bağlı

  Bu bağlamla ilişkili dokümanın UUID'si veya bu bağlam bir dokümanda barındırılmıyorsa tanımlanmamış.

• documentOrigin

  dize isteğe bağlı

  Bu bağlamla ilişkili dokümanın kaynağı veya bağlam bir dokümanda barındırılmıyorsa tanımlanmamış.

• documentUrl

  dize isteğe bağlı

  Bu bağlamla ilişkili dokümanın URL'si veya bağlam bir dokümanda barındırılmıyorsa tanımlanmamış.

• frameId

  sayı

  Bu bağlam için çerçevenin kimliği veya bu bağlam bir çerçevede barındırılmıyorsa -1.

• gizli

  boolean

  Bağlamı gizli profille ilişkilendirip ilişkilendirmediğiniz.

• tabId

  sayı

  Bu bağlamın sekmesinin kimliği veya bu bağlam bir sekmede barındırılmıyorsa -1.

• windowId

  sayı

  Bu bağlam için pencerenin kimliği veya bu bağlam bir pencerede barındırılmıyorsa -1.

MessageSender

İleti veya istek gönderen komut dosyası bağlamı hakkında bilgi içeren bir nesne.

Özellikler

• documentId

  dize isteğe bağlı

  Chrome 106 ve sonraki sürümler

  Bağlantıyı açan dokümanın UUID'si.

• documentLifecycle

  dize isteğe bağlı

  Chrome 106 ve sonraki sürümler

  Bağlantıyı açan dokümanın, bağlantı noktası oluşturulduğu sıradaki yaşam döngüsü. Belgenin yaşam döngüsü durumunun, taşıma işlemi oluşturulduktan sonra değişmiş olabileceğini unutmayın.

• frameId

  number isteğe bağlı

  Bağlantıyı açan çerçeve. Üst düzey çerçeveler için 0, alt çerçeveler için pozitif değerdir. Bu değer yalnızca tab ayarlandığında belirlenir.

• id

  dize isteğe bağlı

  Bağlantıyı açan uzantının kimliği (varsa).

• nativeApplication

  dize isteğe bağlı

  Chrome 74 ve sonraki sürümler

  Varsa bağlantıyı açan yerel uygulamanın adı.

• kaynak

  dize isteğe bağlı

  Chrome 80 ve üzeri sürümler

  Bağlantıyı açan sayfanın veya çerçevenin kaynağı. url mülkünden farklı olabilir (ör. about:blank) veya opak olabilir (ör. korumalı alan iFrame'leri). Bu, URL'den hemen anlaşılamıyorsa kaynağın güvenilir olup olmadığını belirlemek için yararlıdır.

• sekmesinden

  Sekme isteğe bağlı

  Varsa bağlantıyı açan tabs.Tab. Bu özellik yalnızca bağlantı bir sekmeden (içerik komut dosyaları dahil) açıldığında ve yalnızca alıcı bir uygulama değilse uzantıysa mevcut olur.

• tlsChannelId

  dize isteğe bağlı

  Uzantı tarafından istenirse ve varsa bağlantıyı açan sayfanın veya çerçevenin TLS kanal kimliği.

• url

  dize isteğe bağlı

  Bağlantıyı açan sayfanın veya çerçevenin URL'si. Gönderen bir iFrame'deyse bu URL, iFrame'i barındıran sayfanın URL'si değil, iFrame'in URL'sidir.

OnInstalledReason

Chrome 44 ve sonraki sürümler

Bu etkinliğin gönderilme nedeni.

Enum

"install"
Etkinlik nedenini yükleme olarak belirtir.

"update"
Etkinlik nedenini uzantı güncellemesi olarak belirtir.

"chrome_update"
Etkinlik nedenini Chrome güncellemesi olarak belirtir.

"shared_module_update"
Etkinlik nedenini, paylaşılan bir modüldeki güncelleme olarak belirtir.

OnRestartRequiredReason

Chrome 44 ve sonraki sürümler

Etkinliğin gönderilme nedeni. Uygulama yeni bir sürüme güncellendiği için yeniden başlatma gerektiğinde "app_update" kullanılır. Tarayıcı/işletim sistemi yeni bir sürüme güncellendiği için yeniden başlatma gerektiğinde "os_update" kullanılır. "düzenli", sistem kuruluş politikasında belirlenen izin verilen çalışma süresinden daha uzun süre çalıştığında kullanılır.

Enum

"app_update"
Etkinlik nedenini uygulama güncellemesi olarak belirtir.

"os_update"
Etkinlik nedenini işletim sisteminde güncelleme olarak belirtir.

"periodic"
Etkinlik nedenini, uygulamanın periyodik olarak yeniden başlatılması olarak belirtir.

PlatformArch

Chrome 44 ve sonraki sürümler

Makinenin işlemci mimarisi.

Enum

"arm"
İşlemci mimarisini arm olarak belirtir.

"arm64"
İşlemci mimarisini arm64 olarak belirtir.

"x86-32"
İşlemci mimarisini x86-32 olarak belirtir.

"x86-64"
İşlemci mimarisini x86-64 olarak belirtir.

"mips"
İşlemci mimarisini mips olarak belirtir.

"mips64"
İşlemci mimarisini mips64 olarak belirtir.

PlatformInfo

Mevcut platformla ilgili bilgileri içeren bir nesne.

Özellikler

• arch

  PlatformArch

  Makinenin işlemci mimarisi.

• nacl_arch

  PlatformNaclArch

  Yerel istemci mimarisi. Bu, bazı platformlarda arch'tan farklı olabilir.

• os

  PlatformOs

  Chrome'un çalıştığı işletim sistemi.

PlatformNaclArch

Chrome 44 ve sonraki sürümler

Yerel istemci mimarisi. Bu, bazı platformlarda arch'tan farklı olabilir.

Enum

"arm"
Doğal istemci mimarisini arm olarak belirtir.

"x86-32"
Doğal istemci mimarisini x86-32 olarak belirtir.

"x86-64"
Yerli istemci mimarisini x86-64 olarak belirtir.

"mips"
Doğal istemci mimarisini mips olarak belirtir.

"mips64"
Doğal istemci mimarisini mips64 olarak belirtir.

PlatformOs

Chrome 44 ve sonraki sürümler

Chrome'un çalıştığı işletim sistemi.

Enum

"mac"
MacOS işletim sistemini belirtir.

"win"
Windows işletim sistemini belirtir.

"android"
Android işletim sistemini belirtir.

"cros"
Chrome işletim sistemini belirtir.

"linux"
Linux işletim sistemini belirtir.

"openbsd"
OpenBSD işletim sistemini belirtir.

"fuchsia"
Fuchsia işletim sistemini belirtir.

Port

Diğer sayfalarla iki yönlü iletişime izin veren bir nesne. Daha fazla bilgi için Uzun süreli bağlantılar başlıklı makaleyi inceleyin.

Özellikler

• ad

  dize

  runtime.connect çağrısında belirtildiği şekilde bağlantı noktasının adı.

• onDisconnect

  Etkinlik<functionvoidvoid>

  Bağlantı noktası diğer uçlarla bağlantısını kestiğinde tetiklenir. Bağlantı noktası yanlışlıkla kapatılmışsa runtime.lastError ayarlanabilir. Bağlantı noktası disconnect aracılığıyla kapatılırsa bu etkinlik yalnızca diğer tarafta tetiklenir. Bu etkinlik en fazla bir kez tetiklenir (Port lifetime bölümüne de bakın).

  onDisconnect.addListener işlevi şu şekilde görünür:

  (callback: function) => {...}

  • geri çağırma

    işlev

    callback parametresi şu şekilde görünür:

    (port: Port) => void

    • bağlantı noktası

      Bağlantı noktası

• onMessage

  Etkinlik<functionvoidvoid>

  Bu etkinlik, bağlantı noktasının diğer ucu tarafından postMessage çağrıldığında tetiklenir.

  onMessage.addListener işlevi şu şekilde görünür:

  (callback: function) => {...}

  • geri çağırma

    işlev

    callback parametresi şu şekilde görünür:

    (message: any, port: Port) => void

    • mesaj

      herhangi

    • bağlantı noktası

      Bağlantı noktası

• gönderen

  MessageSender isteğe bağlı

  Bu özellik yalnızca onConnect / onConnectExternal / onConnectNative dinleyicilerine iletilen bağlantı noktalarında bulunur.

• bağlantıyı kes

  geçersiz

  Bağlantıyı hemen kesin. Bağlantısı kesilmiş bir bağlantı noktasında disconnect() çağrısı yapılmasının hiçbir etkisi yoktur. Bir bağlantının kesilmesi durumunda bu bağlantıya yeni etkinlik gönderilmez.

  disconnect işlevi şu şekilde görünür:

  () => {...}

• postMessage

  geçersiz

  Bağlantı noktasının diğer ucuna bir mesaj gönderin. Bağlantı noktası bağlantısı kesilirse hata oluşur.

  postMessage işlevi şu şekilde görünür:

  (message: any) => {...}

  • mesaj

    herhangi

    Chrome 52 ve sonraki sürümler

    Gönderilecek mesaj. Bu nesne JSON'a dönüştürülebilir olmalıdır.

RequestUpdateCheckStatus

Chrome 44 ve sonraki sürümler

Güncelleme kontrolünün sonucu.

Enum

"throttled"
Durum kontrolünün sınırlandırıldığını belirtir. Bu durum, kısa süre içinde tekrarlanan kontrollerden sonra ortaya çıkabilir.

"no_update"
Yüklenecek güncelleme olmadığını belirtir.

"update_available"
Yüklenebilecek bir güncelleme olduğunu belirtir.

Özellikler

id

Uzantının/uygulamanın kimliği.

Tür

dize

lastError

Bir API işlevi çağrısı başarısız olursa hata mesajıyla doldurulur. Aksi takdirde tanımlanmaz. Bu yalnızca ilgili işlevin geri çağırma işlevi kapsamında tanımlanır. Bir hata oluşursa ancak geri çağırma içinde runtime.lastError işlevine erişilmezse hatayı oluşturan API işlevini listeleyen bir mesaj konsola kaydedilir. Promise döndüren API işlevleri bu özelliği ayarlamaz.

Tür

nesne

Özellikler

• mesaj

  dize isteğe bağlı

  Oluşmuş hatayla ilgili ayrıntılar.

Yöntemler

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

Bir uzantıdaki (arka plan sayfası gibi) veya diğer uzantılardaki/uygulamalardaki dinleyicileri bağlamaya çalışır. Bu, uzantı süreçlerine bağlanan içerik komut dosyaları, uygulama/uzantılar arası iletişim ve web mesajlaşması için yararlıdır. Bu işlemin, içerik komut dosyasında herhangi bir dinleyiciye bağlanmadığını unutmayın. Uzantılar, tabs.connect aracılığıyla sekmelere yerleştirilmiş içerik komut dosyalarına bağlanabilir.

Parametreler

• extensionId

  dize isteğe bağlı

  Bağlanılacak uzantının kimliği. Atlanırsa kendi uzantınızla bağlantı kurulmaya çalışılır. Web mesajlaşması için bir web sayfasından mesaj gönderiyorsanız gereklidir.

• connectInfo

  nesne isteğe bağlı

  • includeTlsChannelId

    boole isteğe bağlı

    TLS kanal kimliğinin, bağlantı etkinliğini dinleyen işlemler için onConnectExternal işlevine aktarılıp aktarılmayacağı.

  • ad

    dize isteğe bağlı

    Bağlantı etkinliğini dinleyen işlemler için onConnect işlevine iletilir.

İadeler

• Bağlantı noktası

  İletilerin gönderilip alınabileceği bağlantı noktası. Uzantı mevcut değilse bağlantı noktası onDisconnect etkinliği tetiklenir.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Ana makinedeki yerel bir uygulamaya bağlanır. Bu yöntem için "nativeMessaging" izni gerekir. Daha fazla bilgi için Yerel Mesajlaşma bölümüne bakın.

Parametreler

• uygulama

  dize

  Bağlanılacak kayıtlı uygulamanın adı.

İadeler

• Bağlantı noktası

  Uygulamayla mesajların gönderilip alınabileceği bağlantı noktası

getBackgroundPage()

Söz veriyorum Yalnızca ön plan

chrome.runtime.getBackgroundPage(
  callback?: function,
)

Geçerli uzantı/uygulama içinde çalışan arka plan sayfasının JavaScript "pencere" nesnesini alır. Arka plan sayfası bir etkinlik sayfasıysa sistem, geri çağırma işlevini çağırmadan önce sayfanın yüklenmesini sağlar. Arka plan sayfası yoksa bir hata ayarlanır.

Parametreler

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  (backgroundPage?: Window) => void

  • backgroundPage

    Pencere isteğe bağlı

    Arka plan sayfası için JavaScript "pencere" nesnesi.

İadeler

• Promise<Window | undefined>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getContexts()

Promise Chrome 116 ve üzeri MV3 ve üzeri

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Bu uzantıyla ilişkili etkin bağlamlar hakkında bilgi getirir

Parametreler

• filtrele

  ContextFilter

  Eşleşen bağlamları bulmak için bir filtre. Bir bağlam, filtrede belirtilen tüm alanlarla eşleşirse eşleşir. Filtrede belirtilmeyen tüm alanlar tüm bağlamlarla eşleşir.

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  (contexts: ExtensionContext[]) => void

  • bağlamlar

    ExtensionContext[]

    Eşleşen bağlamlar (varsa).

İadeler

• Promise<ExtensionContext[]>

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getManifest()

chrome.runtime.getManifest()

Manifest dosyasından uygulama veya uzantıyla ilgili ayrıntıları döndürür. Döndürülen nesne, manifest dosyasının tamamının serileştirilmesidir.

İadeler

• nesne

  Manifest ayrıntıları.

getPackageDirectoryEntry()

Söz veriyorum Yalnızca ön plan

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Paket dizini için bir DirectoryEntry döndürür.

Parametreler

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

İadeler

• Promise<DirectoryEntry>

  Chrome 122 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getPlatformInfo()

Promise

chrome.runtime.getPlatformInfo(
  callback?: function,
)

Mevcut platformla ilgili bilgileri döndürür.

Parametreler

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

İadeler

• Promise<PlatformInfo>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getURL()

chrome.runtime.getURL(
  path: string,
)

Bir uygulama/uzantı yükleme dizininde bulunan göreli yolu tam nitelikli URL'ye dönüştürür.

Parametreler

• yol

  dize

  Bir uygulama/uzantıdaki kaynağın, yükleme dizine göre ifade edilen yolu.

İadeler

• dize

  Kaynağın tam nitelikli URL'si.

openOptionsPage()

Promise

chrome.runtime.openOptionsPage(
  callback?: function,
)

Mümkünse uzantınızın seçenekler sayfasını açın.

Tam davranış, manifest'inizin options_ui veya options_page anahtarına ya da Chrome'un o anda desteklediğine bağlı olabilir. Örneğin, sayfa yeni bir sekmede, chrome://extensions içinde, bir uygulama içinde açılabilir veya açık bir seçenekler sayfasına odaklanabilir. Bu işlem, arayan sayfasının hiçbir zaman yeniden yüklenmesine neden olmaz.

Uzantı, seçenek sayfası tanımlamıyorsa veya Chrome başka bir nedenle sayfa oluşturamadıysa geri çağırma işlevi lastError değerini ayarlar.

Parametreler

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  () => void

İadeler

• Promise<void>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

reload()

chrome.runtime.reload()

Uygulamayı veya uzantıyı yeniden yükler. Bu yöntem kiosk modunda desteklenmez. Kiosk modu için chrome.runtime.restart() yöntemini kullanın.

requestUpdateCheck()

Promise

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Bu uygulama/uzantı için anında güncelleme kontrolü yapılmasını ister.

Önemli: Chrome zaten birkaç saatte bir otomatik kontroller yaptığından, çoğu uzantı/uygulama bu yöntemi kullanmamalıdır. Ayrıca, requestUpdateCheck'i çağırmanız gerekmeden runtime.onUpdateAvailable etkinliğini dinleyebilirsiniz.

Bu yöntem yalnızca çok sınırlı durumlarda çağrılmaya uygundur. Örneğin, uzantınız bir arka uç hizmetiyle iletişim kuruyorsa ve arka uç hizmeti, istemci uzantısı sürümünün çok eski olduğunu belirlediyse ve kullanıcıdan güncelleme yapmasını istiyorsanız bu yöntemi kullanabilirsiniz. requestUpdateCheck'in diğer kullanımlarının çoğu (ör. tekrarlanan bir zamanlayıcıya göre koşulsuz olarak çağrılması) muhtemelen yalnızca istemci, ağ ve sunucu kaynaklarını boşa harcamaya yarar.

Not: Bir geri çağırma işleviyle çağrıldığında bu işlev, bir nesne döndürmek yerine iki özelliği geri çağırma işlevine iletilen ayrı bağımsız değişkenler olarak döndürür.

Parametreler

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  (result: object) => void

  • sonuç

    nesne

    Chrome 109 ve sonraki sürümler

    Güncelleme kontrolünün durumunu ve güncelleme varsa sonucun tüm ayrıntılarını içeren RequestUpdateCheckResult nesnesi

    • durum

      RequestUpdateCheckStatus

      Güncelleme kontrolünün sonucu.

    • sürüm

      dize isteğe bağlı

      Güncelleme varsa kullanılabilir güncellemenin sürümünü içerir.

İadeler

• Promise<object>

  Chrome 109 ve sonraki sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

restart()

chrome.runtime.restart()

Uygulama kiosk modunda çalışırken ChromeOS cihazı yeniden başlatın. Aksi takdirde işlem yapılmaz.

restartAfterDelay()

Promise Chrome 53 ve sonraki sürümler

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Uygulama, belirtilen saniyeler sonra kiosk modunda çalışırken ChromeOS cihazı yeniden başlatın. Zaman dolmadan tekrar çağrılırsa yeniden başlatma işlemi ertelenir. -1 değeriyle çağrılırsa yeniden başlatma işlemi iptal edilir. Kiosk modu dışında bu işlem yapılamaz. Yalnızca bu API'yi çağıran ilk uzantı tarafından tekrar tekrar çağrılmasına izin verilir.

Parametreler

• saniye

  sayı

  Cihazı yeniden başlatmadan önce bekleme süresi (saniye cinsinden) veya planlanmış bir yeniden başlatmayı iptal etmek için -1.

• geri çağırma

  işlev isteğe bağlı

  callback parametresi şu şekilde görünür:

  () => void

İadeler

• Promise<void>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

sendMessage()

Promise

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Uzantınızdaki veya farklı bir uzantı/uygulamadaki etkinlik dinleyicilerine tek bir mesaj gönderir. runtime.connect ile benzerdir ancak isteğe bağlı bir yanıtla yalnızca tek bir mesaj gönderir. Uzantınıza gönderim yapılıyorsa runtime.onMessage etkinliği, uzantınızın her karede (gönderenin karesi hariç) veya farklı bir uzantıya gönderim yapılıyorsa runtime.onMessageExternal etkinliği tetiklenir. Uzantıların bu yöntemi kullanarak içerik komut dosyalarına mesaj gönderemediğini unutmayın. İçerik komut dosyalarına mesaj göndermek için tabs.sendMessage simgesini kullanın.

Parametreler

• extensionId

  dize isteğe bağlı

  Mesajın gönderileceği uzantının kimliği. Atlanırsa mesaj kendi uzantınıza/uygulamanıza gönderilir. Web mesajlaşma için bir web sayfasından mesaj gönderiyorsanız gereklidir.

• mesaj

  herhangi

  Gönderilecek mesaj. Bu mesaj, JSON'a dönüştürülebilir bir nesne olmalıdır.

• seçenekler

  nesne isteğe bağlı

  • includeTlsChannelId

    boole isteğe bağlı

    TLS kanal kimliğinin, bağlantı etkinliğini dinleyen işlemler için onMessageExternal işlevine aktarılıp aktarılmayacağı.

• geri çağırma

  işlev isteğe bağlı

  Chrome 99 ve üzeri sürümler

  callback parametresi şu şekilde görünür:

  (response: any) => void

  • gönderin

    herhangi

    İletinin işleyicisi tarafından gönderilen JSON yanıt nesnesi. Uzantıya bağlanırken hata oluşursa geri çağırma işlevi bağımsız değişken olmadan çağrılır ve runtime.lastError hata mesajına ayarlanır.

İadeler

• Promise<any>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

sendNativeMessage()

Promise

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Yerel bir uygulamaya tek bir mesaj gönderme. Bu yöntem için "nativeMessaging" izni gerekir.

Parametreler

• uygulama

  dize

  Yerel mesajlaşma ana makinesinin adı.

• mesaj

  nesne

  Yerel mesajlaşma ana makinesine iletilecek mesaj.

• geri çağırma

  işlev isteğe bağlı

  Chrome 99 ve üzeri sürümler

  callback parametresi şu şekilde görünür:

  (response: any) => void

  • gönderin

    herhangi

    Yerel mesajlaşma ana makinesi tarafından gönderilen yanıt mesajı. Yerel mesajlaşma ana makinesine bağlanırken hata oluşursa geri çağırma işlevi bağımsız değişken olmadan çağrılır ve runtime.lastError hata mesajına ayarlanır.

İadeler

• Promise<any>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

setUninstallURL()

Promise

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Kaldırma işleminin ardından ziyaret edilecek URL'yi ayarlar. Bu, sunucu tarafı verileri temizlemek, analiz yapmak ve anketler uygulamak için kullanılabilir. Maksimum 1.023 karakter.

Parametreler

• url

  dize

  Uzantı kaldırıldıktan sonra açılacak URL. Bu URL'de http: veya https: şeması olmalıdır. Kaldırma işleminin ardından yeni bir sekme açılmaması için boş bir dize ayarlayın.

• geri çağırma

  işlev isteğe bağlı

  Chrome 45 ve üzeri sürümler

  callback parametresi şu şekilde görünür:

  () => void

İadeler

• Promise<void>

  Chrome 99 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

Etkinlikler

onBrowserUpdateAvailable

Kullanımdan kaldırıldı

chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Lütfen runtime.onRestartRequired adresini kullanın.

Bir Chrome güncellemesi mevcut olduğunda ancak tarayıcı yeniden başlatılması gerektiği için hemen yüklenmediğinde tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Bir uzantı sürecinden veya içerik komut dosyasından (runtime.connect tarafından) bağlantı oluşturulduğunda tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (port: Port) => void

  • bağlantı noktası

    Bağlantı noktası

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Başka bir uzantıdan (runtime.connect tarafından) veya harici olarak bağlanabilir bir web sitesinden bağlantı oluşturulduğunda tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (port: Port) => void

  • bağlantı noktası

    Bağlantı noktası

onConnectNative

Chrome 76 ve sonraki sürümler

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Yerel bir uygulamadan bağlantı oluşturulduğunda tetiklenir. Bu etkinlik için "nativeMessaging" izni gerekir. Yalnızca Chrome OS'te desteklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (port: Port) => void

  • bağlantı noktası

    Bağlantı noktası

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Uzantının ilk kez yüklenmesi, uzantı yeni bir sürüme güncellendiğinde ve Chrome yeni bir sürüme güncellendiğinde tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (details: object) => void

  • ayrıntılar

    nesne

    • id

      dize isteğe bağlı

      İçe aktarılan ve güncellenen paylaşılan modül uzantısının kimliğini belirtir. Bu yalnızca "reason" değeri "shared_module_update" ise mevcuttur.

    • previousVersion

      dize isteğe bağlı

      Uzantı için kısa süre önce güncellenen önceki sürümü gösterir. Bu yalnızca "reason" değeri "update" ise mevcuttur.

    • neden

      OnInstalledReason

      Bu etkinliğin gönderilme nedeni.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Bir uzantı sürecinden (runtime.sendMessage tarafından) veya içerik komut dosyasından (tabs.sendMessage tarafından) mesaj gönderildiğinde tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • mesaj

    herhangi

  • gönderen

    MessageSender

  • sendResponse

    işlev

    sendResponse parametresi şu şekilde görünür:

    () => void

  • returns

    boole | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Başka bir uzantıdan mesaj gönderildiğinde (runtime.sendMessage tarafından) tetiklenir. İçerik komut dosyasında kullanılamaz.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • mesaj

    herhangi

  • gönderen

    MessageSender

  • sendResponse

    işlev

    sendResponse parametresi şu şekilde görünür:

    () => void

  • returns

    boole | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Bir uygulamanın veya çalıştığı cihazın yeniden başlatılması gerektiğinde tetiklenir. Uygulama, yeniden başlatmanın gerçekleşmesi için en uygun zamanda tüm pencerelerini kapatmalıdır. Uygulama hiçbir işlem yapmazsa 24 saatlik ek sürenin ardından yeniden başlatma işlemi zorunlu kılınacaktır. Bu etkinlik şu anda yalnızca Chrome OS kiosk uygulamaları için tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (reason: OnRestartRequiredReason) => void

  • neden

    OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Bu uzantının yüklü olduğu bir profil ilk kez başlatıldığında tetiklenir. Bu uzantı "bölünmüş" gizli modda çalışıyor olsa bile bir gizli profil başlatıldığında bu etkinlik tetiklenmez.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Etkinlik sayfası yüklenmeden hemen önce gönderilir. Bu sayede uzantı, bazı temizlik işlemlerini yapabilir. Sayfa yüklenmediğinden, bu etkinlik işlenirken başlatılan tüm asenkron işlemlerin tamamlanmasının garanti edilmediğini unutmayın. Etkinlik sayfası yüklenmeden önce daha fazla etkinlik gerçekleşirse onSuspendCanceled etkinliği gönderilir ve sayfa yüklenmez.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

Uygulamanın yine de kaldırılmayacağını belirtmek için onSuspend çağrısından sonra gönderilir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Bir güncelleme mevcut olduğunda ancak uygulama şu anda çalıştığı için hemen yüklenmediğinde tetiklenir. Hiçbir şey yapmazsanız güncelleme, arka plan sayfası bir sonraki sefer yüklendiğinde yüklenir. Güncellemenin daha erken yüklenmesini istiyorsanız chrome.runtime.reload() işlevini açıkça çağırabilirsiniz. Uzantılarınız kalıcı bir arka plan sayfası kullanıyorsa arka plan sayfası hiçbir zaman yüklenmez. Bu nedenle, bu etkinliğe yanıt olarak chrome.runtime.reload() işlevini manuel olarak çağırmadığınız sürece güncelleme, Chrome'un bir sonraki yeniden başlatılmasına kadar yüklenmez. Bu etkinliği dinleyen hiçbir işleyici yoksa ve uzantınızda kalıcı bir arka plan sayfası varsa bu etkinliğe yanıt olarak chrome.runtime.reload() çağrılıyormuş gibi davranır.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (details: object) => void

  • ayrıntılar

    nesne

    • sürüm

      dize

      Mevcut güncellemenin sürüm numarası.

onUserScriptConnect

Chrome 115+ MV3+

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Bu uzantının kullanıcı komut dosyasından bağlantı oluşturulduğunda tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (port: Port) => void

  • bağlantı noktası

    Bağlantı noktası

onUserScriptMessage

Chrome 115+ MV3+

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Aynı uzantı ile ilişkili bir kullanıcı komut dosyasından ileti gönderildiğinde tetiklenir.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • mesaj

    herhangi

  • gönderen

    MessageSender

  • sendResponse

    işlev

    sendResponse parametresi şu şekilde görünür:

    () => void

  • returns

    boole | undefined