chrome.runtime

refresh date: 2026-09-25 robots: noindex

Beschreibung

Verwenden Sie die chrome.runtime API, um den Service Worker abzurufen, Details zum Manifest zurückzugeben und auf Ereignisse im Lebenszyklus der Erweiterung zu warten und darauf zu reagieren. Sie können diese API auch verwenden, um den relativen Pfad von URLs in vollständig qualifizierte URLs umzuwandeln.

Übersicht

Die Runtime API bietet Methoden zur Unterstützung einer Reihe von Funktionsbereichen, die Ihre Erweiterungen verwenden können:

Nachrichtenweitergabe

Ihre Erweiterung kann mit verschiedenen Kontexten innerhalb Ihrer Erweiterung und auch mit anderen Erweiterungen über die folgenden Methoden und Ereignisse kommunizieren: connect(), onConnect, onConnectExternal, sendMessage(), onMessage und onMessageExternal. Außerdem kann Ihre Erweiterung mithilfe von connectNative() und sendNativeMessage() Nachrichten an native Anwendungen auf dem Gerät des Nutzers weitergeben.

Hinweis: Eine Übersicht zu diesem Thema finden Sie unter Message Passing.

Auf Erweiterungs- und Plattformmetadaten zugreifen

Mit diesen Methoden können Sie verschiedene spezifische Metadaten zur Erweiterung und zur Plattform abrufen. Zu den Methoden in dieser Kategorie gehören getManifest() und getPlatformInfo().

Lebenszyklus und Optionen von Erweiterungen verwalten

Mit diesen Eigenschaften können Sie einige Metavorgänge für die Erweiterung ausführen und die Optionsseite aufrufen. Zu den Methoden und Ereignissen in dieser Kategorie gehören onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() und setUninstallURL().

Hilfsprogramme

Diese Methoden bieten nützliche Funktionen wie die Konvertierung interner Ressourcendarstellungen in externe Formate. Zu den Methoden in dieser Kategorie gehört getURL().

Dienstprogramme für den Kioskmodus

Diese Methoden sind nur unter ChromeOS verfügbar und dienen hauptsächlich der Unterstützung von Kioskimplementierungen. Zu den Methoden in dieser Kategorie gehören restart und restartAfterDelay.

Berechtigungen

Die meisten Methoden der Runtime API erfordern keine Berechtigung, mit Ausnahme von sendNativeMessage und connectNative, für die die Berechtigung nativeMessaging erforderlich ist.

Manifest

Im folgenden Beispiel wird gezeigt, wie die Berechtigung nativeMessaging im Manifest deklariert wird:

manifest.json:

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

Anwendungsfälle

Bild zu einer Webseite hinzufügen

Damit eine Webseite auf ein Asset zugreifen kann, das auf einer anderen Domain gehostet wird, muss die vollständige URL der Ressource angegeben werden (z.B. <img src="https://example.com/logo.png">). Das gilt auch für das Einbinden eines Erweiterungs-Assets auf einer Webseite. Die beiden Unterschiede bestehen darin, dass die Assets der Erweiterung als über das Web zugängliche Ressourcen verfügbar gemacht werden müssen und dass in der Regel Inhaltsskripts für das Einfügen von Erweiterungs-Assets verantwortlich sind.

In diesem Beispiel fügt die Erweiterung der Seite, in die das Inhaltsskript eingefügt wird, logo.png hinzu. Dazu wird runtime.getURL() verwendet, um eine vollständig qualifizierte URL zu erstellen. Zuerst muss das Asset im Manifest als über das Web zugängliche Ressource deklariert werden.

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);
}

Daten vom Service Worker an ein Inhaltsskript senden

Es kommt häufig vor, dass die Inhaltsskripts einer Erweiterung Daten benötigen, die von einem anderen Teil der Erweiterung verwaltet werden, z. B. vom Service Worker. Ähnlich wie bei zwei Browserfenstern, die auf derselben Webseite geöffnet sind, können diese beiden Kontexte nicht direkt auf die Werte des jeweils anderen zugreifen. Stattdessen kann die Erweiterung die Nachrichtenweitergabe verwenden, um die verschiedenen Kontexte zu koordinieren.

In diesem Beispiel benötigt das Inhaltsskript einige Daten vom Service Worker der Erweiterung, um die Benutzeroberfläche zu initialisieren. Um diese Daten abzurufen, wird eine get-user-data-Nachricht an den Service Worker übergeben, der mit einer Kopie der Nutzerinformationen antwortet.

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);
});

background.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);
  }
});

Feedback zur Deinstallation einholen

Viele Erweiterungen verwenden Umfragen nach der Deinstallation, um herauszufinden, wie die Erweiterung die Nutzer besser unterstützen und die Nutzerbindung verbessern könnte. Das folgende Beispiel zeigt, wie Sie diese Funktion hinzufügen.

background.js:

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

Beispiele für Erweiterungen

Weitere Beispiele für die Runtime API finden Sie in der Demo zu Manifest V3 – Web Accessible Resources.

Typen

ContextFilter

Chrome 114 oder höher

Ein Filter, der mit bestimmten Erweiterungskontexten abgeglichen werden soll. Übereinstimmende Kontexte müssen allen angegebenen Filtern entsprechen. Jeder nicht angegebene Filter entspricht allen verfügbaren Kontexten. Ein Filter mit `{}` stimmt also mit allen verfügbaren Kontexten überein.

Attribute

• contextIds

  string[] optional

• contextTypes

  ContextType[] optional

• documentIds

  string[] optional

• documentOrigins

  string[] optional

• documentUrls

  string[] optional

• frameIds

  number[] optional

• inkognito

  Boolesch optional

• tabIds

  number[] optional

• windowIds

  number[] optional

ContextType

Chrome 114 oder höher

Enum

"TAB"
Gibt den Kontexttyp als Tab an

"POPUP"
Gibt den Kontexttyp als Pop-up-Fenster der Erweiterung an

"BACKGROUND"
Gibt den Kontexttyp als Service Worker an.

"OFFSCREEN_DOCUMENT"
Gibt den Kontexttyp als Offscreen-Dokument an.

"SIDE_PANEL"
Gibt den Kontexttyp als Seitenleiste an.

"DEVELOPER_TOOLS"
Gibt den Kontexttyp als Entwicklertools an.

ExtensionContext

Chrome 114 oder höher

Ein Kontext, der Erweiterungsinhalte hostet.

Attribute

• Kontext-ID

  String

  Eine eindeutige Kennung für diesen Kontext

• contextType

  ContextType

  Der Kontexttyp, dem dies entspricht.

• documentId

  String optional

  Eine UUID für das Dokument, das mit diesem Kontext verknüpft ist, oder „undefined“, wenn dieser Kontext nicht in einem Dokument gehostet wird.

• documentOrigin

  String optional

  Der Ursprung des Dokuments, das mit diesem Kontext verknüpft ist, oder „undefined“, wenn der Kontext nicht in einem Dokument gehostet wird.

• documentUrl

  String optional

  Die URL des Dokuments, das mit diesem Kontext verknüpft ist, oder „undefined“, wenn der Kontext nicht in einem Dokument gehostet wird.

• frameId

  Zahl

  Die ID des Frames für diesen Kontext oder -1, wenn dieser Kontext nicht in einem Frame gehostet wird.

• inkognito

  boolean

  Gibt an, ob der Kontext mit einem Inkognitoprofil verknüpft ist.

• tabId

  Zahl

  Die ID des Tabs für diesen Kontext oder -1, wenn dieser Kontext nicht in einem Tab gehostet wird.

• windowId

  Zahl

  Die ID des Fensters für diesen Kontext oder -1, wenn dieser Kontext nicht in einem Fenster gehostet wird.

ExtensionLoadDetails

Chrome 157 oder höher

Details zum Ladeereignis der Erweiterung.

Attribute

• previousVersion

  String optional

  Gibt die vorherige Version der Erweiterung an. Dies ist nur vorhanden, wenn „reason“ „update“ oder „enable“ ist. Wenn „reason“ den Wert „update“ hat, ist dies die Version der Erweiterung vor dem Update. Wenn „reason“ den Wert „enable“ hat, ist dies die aktuelle Version der Erweiterung.

• reason

  OnLoadedReason

  Der Grund, warum dieses Ereignis gesendet wird.

MessageSender

Ein Objekt mit Informationen zum Scriptkontext, der eine Nachricht oder Anfrage gesendet hat.

Attribute

• documentId

  String optional

  Chrome 106 oder höher

  Eine UUID des Dokuments, das die Verbindung geöffnet hat.

• documentLifecycle

  String optional

  Chrome 106 oder höher

  Der Lebenszyklus des Dokuments, das die Verbindung geöffnet hat, zum Zeitpunkt der Erstellung des Ports. Der Lebenszyklusstatus des Dokuments kann sich seit der Erstellung des Ports geändert haben.

• frameId

  number optional

  Der Frame, der die Verbindung geöffnet hat. 0 für Frames der obersten Ebene, positiv für untergeordnete Frames. Wird nur festgelegt, wenn tab festgelegt ist.

• id

  String optional

  Die ID der Erweiterung, die die Verbindung geöffnet hat, falls vorhanden.

• nativeApplication

  String optional

  Chrome 74 oder höher

  Der Name der nativen Anwendung, die die Verbindung geöffnet hat, falls vorhanden.

• origin

  String optional

  Chrome 80 oder höher

  Der Ursprung der Seite oder des Frames, von der bzw. dem die Verbindung geöffnet wurde. Sie kann von der URL-Property abweichen (z.B. about:blank) oder intransparent sein (z.B. iFrames in einer Sandbox). Das ist nützlich, um festzustellen, ob die Quelle vertrauenswürdig ist, wenn wir das nicht sofort anhand der URL erkennen können.

• Tabulatortaste

  Tab optional

  Die tabs.Tab, die die Verbindung geöffnet hat, falls vorhanden. Diese Property ist nur vorhanden, wenn die Verbindung über einen Tab (einschließlich Inhaltsskripts) geöffnet wurde, und nur, wenn der Empfänger eine Erweiterung und keine App ist.

• tlsChannelId

  String optional

  Die TLS-Kanal-ID der Seite oder des Frames, über die bzw. den die Verbindung geöffnet wurde, sofern von der Erweiterung angefordert und verfügbar.

• URL

  String optional

  Die URL der Seite oder des Frames, über die bzw. den die Verbindung geöffnet wurde. Wenn sich der Absender in einem iFrame befindet, ist es die URL des iFrames und nicht die URL der Seite, auf der er gehostet wird.

OnInstalledReason

Chrome 44 oder höher

Der Grund, warum dieses Ereignis gesendet wird.

Enum

"install"
Gibt den Grund für das Ereignis als Installation an.

"update"
Gibt den Grund für das Ereignis als Erweiterungsupdate an.

"chrome_update"
Gibt als Grund für das Ereignis ein Chrome-Update an.

"shared_module_update"
Gibt den Ereignisgrund als Aktualisierung eines freigegebenen Moduls an.

OnLoadedReason

Chrome 157 oder höher

Der Grund, warum dieses Ereignis gesendet wird.

Enum

"install"
Die Erweiterung wurde neu installiert.

"update"
Die Erweiterung wurde nach einem Update neu geladen.

"browser_update"
Der Browser wurde auf eine neue Version aktualisiert.

"enable"
Die Erweiterung wurde wieder aktiviert, nachdem sie deaktiviert war.

"startup"
Die Erweiterung wird beim Start des Browsers geladen.

"reload"
Die Erweiterung wurde neu geladen (z.B. über chrome.runtime.reload() oder manuell durch den Nutzer).

OnRestartRequiredReason

Chrome 44 oder höher

Der Grund, warum das Ereignis gesendet wird. „app_update“ wird verwendet, wenn der Neustart erforderlich ist, weil die Anwendung auf eine neuere Version aktualisiert wird. „os_update“ wird verwendet, wenn der Neustart erforderlich ist, weil der Browser oder das Betriebssystem auf eine neuere Version aktualisiert wird. „periodic“ wird verwendet, wenn das System länger als die in der Unternehmensrichtlinie festgelegte zulässige Betriebszeit ausgeführt wird.

Enum

"app_update"
Gibt den Grund für das Ereignis als Update der App an.

"os_update"
Gibt als Grund für das Ereignis ein Update des Betriebssystems an.

"periodic"
Gibt den Ereignisgrund als regelmäßigen Neustart der App an.

PlatformArch

Chrome 44 oder höher

Die Prozessorarchitektur der Maschine.

Enum

"arm"
Gibt die Prozessorarchitektur als „arm“ an.

"arm64"
Gibt die Prozessorarchitektur als arm64 an.

"x86-32"
Gibt die Prozessorarchitektur als x86-32 an.

"x86-64"
Gibt die Prozessorarchitektur als x86-64 an.

"mips"
Gibt die Prozessorarchitektur als mips an.

"mips64"
Gibt die Prozessorarchitektur als mips64 an.

"riscv64"
Gibt die Prozessorarchitektur als riscv64 an.

PlatformInfo

Ein Objekt mit Informationen zur aktuellen Plattform.

Attribute

• arch

  PlatformArch

  Die Prozessorarchitektur der Maschine.

• nacl_arch

  PlatformNaclArch optional

  Seit Chrome 149 veraltet

  Dieses Attribut wird nach der vollständigen Entfernung von Native Client eingestellt.

  Die native Client-Architektur. Dies kann sich auf einigen Plattformen von „arch“ unterscheiden.

• os

  PlatformOs

  Das Betriebssystem, auf dem Chrome ausgeführt wird.

PlatformNaclArch

Chrome 44 und höher Eingestellt seit Chrome 149

Diese Enum ist nach der vollständigen Entfernung von Native Client veraltet.

Die native Client-Architektur. Dies kann sich auf einigen Plattformen von „arch“ unterscheiden.

Enum

"arm"
Gibt die native Clientarchitektur als „arm“ an.

"x86-32"
Gibt die Native Client-Architektur als x86-32 an.

"x86-64"
Gibt die native Clientarchitektur als x86-64 an.

"mips"
Gibt die Native Client-Architektur als „mips“ an.

"mips64"
Gibt die native Clientarchitektur als mips64 an.

PlatformOs

Chrome 44 oder höher

Das Betriebssystem, auf dem Chrome ausgeführt wird.

Enum

"mac"
Gibt das Betriebssystem macOS an.

"win"
Gibt das Windows-Betriebssystem an.

"android"
Gibt das Android-Betriebssystem an.

"cros"
Gibt das Chrome-Betriebssystem an.

"linux"
Gibt das Linux-Betriebssystem an.

"openbsd"
Gibt das OpenBSD-Betriebssystem an.

Port

Ein Objekt, das die bidirektionale Kommunikation mit anderen Seiten ermöglicht. Weitere Informationen finden Sie unter Langlebige Verbindungen.

Attribute

• name

  String

  Der Name des Ports, wie im Aufruf von runtime.connect angegeben.

• onDisconnect

  Event<functionvoidvoid>

  Wird ausgelöst, wenn der Port von den anderen Enden getrennt wird. runtime.lastError kann festgelegt werden, wenn die Verbindung zum Port aufgrund eines Fehlers getrennt wurde. Wenn der Port über disconnect geschlossen wird, wird dieses Ereignis nur am anderen Ende ausgelöst. Dieses Ereignis wird höchstens einmal ausgelöst (siehe auch Port-Lebensdauer).

  Die Funktion onDisconnect.addListener sieht so aus:

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

  • callback

    Funktion

    Der Parameter callback sieht so aus:

    (port: Port) => void

    • Port

      Port

• onMessage

  Event<functionvoidvoid>

  Dieses Ereignis wird ausgelöst, wenn postMessage vom anderen Ende des Ports aufgerufen wird.

  Die Funktion onMessage.addListener sieht so aus:

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

  • callback

    Funktion

    Der Parameter callback sieht so aus:

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

    • Nachricht

      beliebig

    • Port

      Port

• Sender

  MessageSender optional

  Diese Property ist nur für Ports vorhanden, die an onConnect- / onConnectExternal- / onConnectNative-Listener übergeben werden.

• Verknüpfung aufheben

  void

  Trennen Sie den Port sofort. Der Aufruf von disconnect() für einen bereits getrennten Port hat keine Auswirkungen. Wenn die Verbindung zu einem Port getrennt wird, werden keine neuen Ereignisse mehr an diesen Port gesendet.

  Die Funktion disconnect sieht so aus:

  () => {...}

• postMessage

  void

  Senden Sie eine Nachricht an das andere Ende des Ports. Wenn die Verbindung zum Port getrennt wird, wird ein Fehler ausgegeben.

  Die Funktion postMessage sieht so aus:

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

  • Nachricht

    beliebig

    Chrome 52 oder höher

    Die zu sendende Nachricht. Dieses Objekt sollte JSON-fähig sein.

RequestUpdateCheckStatus

Chrome 44 oder höher

Ergebnis der Suche nach Updates.

Enum

"throttled"
Gibt an, dass die Statusprüfung gedrosselt wurde. Das kann passieren, wenn innerhalb kurzer Zeit wiederholt Prüfungen durchgeführt werden.

"no_update"
Gibt an, dass keine Updates zur Installation verfügbar sind.

"update_available"
Gibt an, dass ein Update zur Installation verfügbar ist.

Attribute

id

Die ID der Erweiterung/App.

Typ

String

lastError

Wird mit einer Fehlermeldung ausgefüllt, wenn der Aufruf einer API-Funktion fehlschlägt, andernfalls „undefined“. Diese wird nur im Rahmen des Callbacks dieser Funktion definiert. Wenn ein Fehler auftritt, aber innerhalb des Callbacks nicht auf runtime.lastError zugegriffen wird, wird eine Nachricht in der Console protokolliert, in der die API-Funktion aufgeführt ist, die den Fehler verursacht hat. API-Funktionen, die Promises zurückgeben, legen dieses Attribut nicht fest.

Typ

Objekt

Attribute

• Nachricht

  String optional

  Details zum aufgetretenen Fehler.

Methoden

connect()

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

Versucht, Listener innerhalb einer Erweiterung (z. B. der Hintergrundseite) oder andere Erweiterungen/Apps zu verbinden. Das ist nützlich für Inhaltsskripts, die eine Verbindung zu ihren Erweiterungsprozessen herstellen, für die Kommunikation zwischen Apps/Erweiterungen und für Web-Messaging. Beachten Sie, dass dadurch keine Verbindung zu Listenern in einem Inhaltsskript hergestellt wird. Erweiterungen können über tabs.connect eine Verbindung zu Inhaltsskripts herstellen, die in Tabs eingebettet sind.

Parameter

• extensionId

  String optional

  Die ID der Erweiterung, zu der eine Verbindung hergestellt werden soll. Wenn Sie diese Angabe weglassen, wird versucht, eine Verbindung mit Ihrer eigenen Erweiterung herzustellen. Erforderlich, wenn Nachrichten von einer Webseite für Web-Messaging gesendet werden.

• connectInfo

  Objekt optional

  • includeTlsChannelId

    Boolesch optional

    Gibt an, ob die TLS-Kanal-ID an „onConnectExternal“ für Prozesse übergeben wird, die auf das Verbindungsereignis warten.

  • name

    String optional

    Wird an „onConnect“ für Prozesse übergeben, die auf das Verbindungsereignis warten.

Ausgabe

• Port

  Port, über den Nachrichten gesendet und empfangen werden können. Das onDisconnect-Ereignis des Ports wird ausgelöst, wenn die Erweiterung nicht vorhanden ist.

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

Stellt eine Verbindung zu einer nativen Anwendung auf dem Hostcomputer her. Für diese Methode ist die Berechtigung "nativeMessaging" erforderlich. Weitere Informationen finden Sie unter Native Messaging.

Parameter

• Anwendung

  String

  Der Name der registrierten Anwendung, zu der eine Verbindung hergestellt werden soll.

Ausgabe

• Port

  Port, über den Nachrichten mit der Anwendung gesendet und empfangen werden können

getBackgroundPage()

Promise Nur im Vordergrund Seit Chrome 133 eingestellt

chrome.runtime.getBackgroundPage(
  callback?: function,
): Promise<Window | undefined>

In MV3-Erweiterungen gibt es keine Hintergrundseiten.

Ruft das JavaScript-Objekt „window“ für die Hintergrundseite ab, die in der aktuellen Erweiterung/App ausgeführt wird. Wenn die Hintergrundseite eine Ereignisseite ist, wird sie vor dem Aufruf des Callbacks geladen. Wenn keine Hintergrundseite vorhanden ist, wird ein Fehler ausgegeben.

Parameter

• callback

  function optional

  Der Parameter callback sieht so aus:

  (backgroundPage?: Window) => void

  • backgroundPage

    Fenster optional

    Das JavaScript-Objekt „window“ für die Hintergrundseite.

Ausgabe

• Promise<Window | undefined>

  Chrome 99 oder höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getManifest()

chrome.runtime.getManifest(): object

Gibt Details zur App oder Erweiterung aus dem Manifest zurück. Das zurückgegebene Objekt ist eine Serialisierung der vollständigen Manifestdatei.

Ausgabe

• Objekt

  Die Manifestdetails.

getPackageDirectoryEntry()

Promise Nur Vordergrund

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

Gibt einen DirectoryEntry für das Paketverzeichnis zurück.

Parameter

• callback

  function optional

  Der Parameter callback sieht so aus:

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

Ausgabe

• Promise<DirectoryEntry>

  Chrome 122 oder höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getPlatformInfo()

Promise

chrome.runtime.getPlatformInfo(
  callback?: function,
): Promise<PlatformInfo>

Gibt Informationen zur aktuellen Plattform zurück.

Parameter

• callback

  function optional

  Der Parameter callback sieht so aus:

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

Ausgabe

• Promise<PlatformInfo>

  Chrome 99 oder höher

  Promise, das mit Informationen zur aktuellen Plattform aufgelöst wird.

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getURL()

chrome.runtime.getURL(
  path: string,
): string

Konvertiert einen relativen Pfad innerhalb eines Installationsverzeichnisses einer App oder Erweiterung in eine vollständig qualifizierte URL.

Parameter

• Pfad

  String

  Ein Pfad zu einer Ressource innerhalb einer App oder Erweiterung, der relativ zum Installationsverzeichnis angegeben wird.

Ausgabe

• String

  Die vollständig qualifizierte URL zur Ressource.

getVersion()

Chrome 143 und höher

chrome.runtime.getVersion(): string

Gibt die Version der Erweiterung zurück, wie sie im Manifest deklariert ist.

Ausgabe

• String

  Die Version der Erweiterung.

openOptionsPage()

Promise

chrome.runtime.openOptionsPage(
  callback?: function,
): Promise<void>

Öffnen Sie die Optionsseite Ihrer Erweiterung, falls möglich.

Das genaue Verhalten kann vom Schlüssel options_ui oder options_page des Manifests oder von der aktuellen Unterstützung durch Chrome abhängen. Die Seite kann beispielsweise in einem neuen Tab, in chrome://extensions, in einer App oder einfach auf einer geöffneten Optionsseite geöffnet werden. Die aufrufende Seite wird dadurch nie neu geladen.

Wenn für Ihre Erweiterung keine Optionsseite deklariert ist oder Chrome aus einem anderen Grund keine erstellen konnte, wird durch den Callback lastError festgelegt.

Parameter

• callback

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 99 oder höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

reload()

chrome.runtime.reload(): void

Lädt die App oder Erweiterung neu. Diese Methode wird im Kioskmodus nicht unterstützt. Verwenden Sie für den Kioskmodus die Methode „chrome.runtime.restart()“.

requestUpdateCheck()

Promise

chrome.runtime.requestUpdateCheck(
  callback?: function,
): Promise<object>

Fordert eine sofortige Updateprüfung für diese App/Erweiterung an.

Wichtig: Die meisten Erweiterungen/Apps sollten diese Methode nicht verwenden, da Chrome bereits alle paar Stunden automatische Prüfungen durchführt und Sie auf das Ereignis runtime.onUpdateAvailable warten können, ohne „requestUpdateCheck“ aufrufen zu müssen.

Diese Methode sollte nur in sehr begrenzten Fällen aufgerufen werden, z. B. wenn Ihre Erweiterung mit einem Backend-Dienst kommuniziert und der Backend-Dienst festgestellt hat, dass die Version der Clienterweiterung sehr veraltet ist und Sie den Nutzer auffordern möchten, sie zu aktualisieren. Die meisten anderen Verwendungen von requestUpdateCheck, z. B. der bedingungslose Aufruf basierend auf einem sich wiederholenden Timer, dienen wahrscheinlich nur dazu, Client-, Netzwerk- und Serverressourcen zu verschwenden.

Hinweis: Wenn diese Funktion mit einem Callback aufgerufen wird, gibt sie kein Objekt zurück, sondern die beiden Properties als separate Argumente, die an den Callback übergeben werden.

Parameter

• callback

  function optional

  Der Parameter callback sieht so aus:

  (result: object) => void

  • Ergebnis

    Objekt

    Chrome 109 und höher

    RequestUpdateCheckResult-Objekt, das den Status der Updateprüfung und alle Details des Ergebnisses enthält, wenn ein Update verfügbar ist

    • Status

      RequestUpdateCheckStatus

      Ergebnis der Suche nach Updates.

    • Version

      String optional

      Wenn ein Update verfügbar ist, enthält dieses Feld die Version des verfügbaren Updates.

Ausgabe

• Promise<object>

  Chrome 109 und höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

restart()

chrome.runtime.restart(): void

Starten Sie das ChromeOS-Gerät neu, wenn die App im Kioskmodus ausgeführt wird. Andernfalls wird keine Aktion ausgeführt.

restartAfterDelay()

Promise Chrome 53 und höher

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

Das ChromeOS-Gerät wird nach der angegebenen Anzahl von Sekunden neu gestartet, wenn die App im Kioskmodus ausgeführt wird. Wenn die Funktion vor Ablauf der Zeit noch einmal aufgerufen wird, wird der Neustart verzögert. Wenn der Wert „-1“ angegeben wird, wird der Neustart abgebrochen. Im Nicht-Kioskmodus ist dies ein No-Op. Sie darf nur von der ersten Erweiterung, die diese API aufruft, wiederholt aufgerufen werden.

Parameter

• Sekunden

  Zahl

  Wartezeit in Sekunden vor dem Neustart des Geräts oder „-1“, um einen geplanten Neustart abzubrechen.

• callback

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 99 oder höher

  Promise, das aufgelöst wird, wenn eine Neustartanfrage erfolgreich verschoben wurde.

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

sendMessage()

Promise

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

Sendet eine einzelne Nachricht an Ereignis-Listener in Ihrer Erweiterung oder einer anderen Erweiterung/App. Ähnlich wie runtime.connect, sendet aber nur eine einzelne Nachricht mit einer optionalen Antwort. Wenn die Nachricht an deine Erweiterung gesendet wird, wird das Ereignis runtime.onMessage in jedem Frame deiner Erweiterung ausgelöst (außer im Frame des Absenders). Wenn die Nachricht an eine andere Erweiterung gesendet wird, wird das Ereignis runtime.onMessageExternal ausgelöst. Beachten Sie, dass Erweiterungen mit dieser Methode keine Nachrichten an Content-Scripts senden können. Verwenden Sie tabs.sendMessage, um Nachrichten an Inhaltsskripts zu senden.

Parameter

• extensionId

  String optional

  Die ID der Erweiterung, an die die Nachricht gesendet werden soll. Wenn Sie diesen Parameter weglassen, wird die Nachricht an Ihre eigene Erweiterung/App gesendet. Erforderlich, wenn Nachrichten von einer Webseite für Web-Messaging gesendet werden.

• Nachricht

  beliebig

  Die zu sendende Nachricht. Diese Nachricht sollte ein JSON-fähiges Objekt sein.

• Optionen

  Objekt optional

  • includeTlsChannelId

    Boolesch optional

    Gibt an, ob die TLS-Kanal-ID an „onMessageExternal“ für Prozesse übergeben wird, die auf das Verbindungsereignis warten.

• callback

  function optional

  Chrome 99 oder höher

  Der Parameter callback sieht so aus:

  (response: any) => void

  • Antwort

    beliebig

    Das JSON-Antwortobjekt, das vom Handler der Nachricht gesendet wird. Wenn beim Herstellen der Verbindung zur Erweiterung ein Fehler auftritt, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Ausgabe

• Promise<any>

  Chrome 99 oder höher

  In Chrome 99 wurde die Unterstützung für Promises für Erweiterungskontexte hinzugefügt. Bei der Kommunikation von einer Webseite zu einer Erweiterung sind Promises ab Chrome 118 verfügbar.

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

sendNativeMessage()

Promise

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
): Promise<any>

Eine einzelne Nachricht an eine native Anwendung senden. Für diese Methode ist die Berechtigung "nativeMessaging" erforderlich.

Parameter

• Anwendung

  String

  Der Name des Hosts für natives Messaging oder die Zieldetails.

• Nachricht

  Objekt

  Die Nachricht, die an den Host für natives Messaging übergeben wird.

• callback

  function optional

  Chrome 99 oder höher

  Der Parameter callback sieht so aus:

  (response: any) => void

  • Antwort

    beliebig

    Die vom Host für natives Messaging gesendete Antwortnachricht. Wenn beim Herstellen der Verbindung zum Host für natives Messaging ein Fehler auftritt, wird der Callback ohne Argumente aufgerufen und runtime.lastError wird auf die Fehlermeldung gesetzt.

Ausgabe

• Promise<any>

  Chrome 99 oder höher

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

setUninstallURL()

Promise

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
): Promise<void>

Legt die URL fest, die bei der Deinstallation aufgerufen werden soll. Dies kann verwendet werden, um serverseitige Daten zu bereinigen, Analysen durchzuführen und Umfragen zu implementieren. Maximal 1.023 Zeichen.

Parameter

• URL

  String

  URL, die nach der Deinstallation der Erweiterung geöffnet werden soll. Diese URL muss ein http:- oder https:-Schema haben. Legen Sie einen leeren String fest, damit nach der Deinstallation kein neuer Tab geöffnet wird.

• callback

  function optional

  Chrome 45 oder höher

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 99 oder höher

  Promise, das aufgelöst wird, wenn die Deinstallations-URL festgelegt ist. Wenn die angegebene URL ungültig ist, wird das Promise abgelehnt.

  Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onBrowserUpdateAvailable

Eingestellt

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

Bitte verwende runtime.onRestartRequired.

Wird ausgelöst, wenn ein Chrome-Update verfügbar ist, aber nicht sofort installiert wird, weil ein Browserneustart erforderlich ist.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  () => void

onConnect

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

Wird ausgelöst, wenn eine Verbindung von einem Erweiterungsprozess oder einem Inhaltsskript (über runtime.connect) hergestellt wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (port: Port) => void

  • Port

    Port

onConnectExternal

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

Wird ausgelöst, wenn eine Verbindung von einer anderen Erweiterung (über runtime.connect) oder von einer extern verbindbaren Website hergestellt wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (port: Port) => void

  • Port

    Port

onConnectNative

Chrome 76 oder höher

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

Wird ausgelöst, wenn eine Verbindung von einer nativen Anwendung hergestellt wird. Für dieses Ereignis ist die Berechtigung "nativeMessaging" erforderlich. Sie wird nur unter ChromeOS unterstützt.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (port: Port) => void

  • Port

    Port

onEnabled

Chrome 155 oder höher

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

Wird ausgelöst, wenn eine Erweiterung von einem deaktivierten in einen aktivierten Zustand wechselt.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  () => void

onExtensionLoaded

Chrome 157 oder höher

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

Wird ausgelöst, wenn die Erweiterung der Gruppe aktiver Erweiterungen hinzugefügt wird. Das kann in verschiedenen Szenarien passieren: wenn eine Erweiterung zum ersten Mal installiert wird, wenn sie auf eine neue Version aktualisiert wird, wenn sie nach der Deaktivierung wieder aktiviert wird, wenn sie neu geladen wird, wenn sie beim Start des Browsers geladen wird oder wenn sie geladen wird, wenn der Browser auf eine neue Version aktualisiert wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (details: ExtensionLoadDetails) => void

  • Details

    ExtensionLoadDetails

onInstalled

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

Wird ausgelöst, wenn die Erweiterung zum ersten Mal installiert wird, wenn die Erweiterung auf eine neue Version aktualisiert wird und wenn Chrome auf eine neue Version aktualisiert wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (details: object) => void

  • Details

    Objekt

    • id

      String optional

      Gibt die ID der importierten Erweiterung für freigegebene Module an, die aktualisiert wurde. Dies ist nur vorhanden, wenn „reason“ den Wert „shared_module_update“ hat.

    • previousVersion

      String optional

      Gibt die vorherige Version der Erweiterung an, die gerade aktualisiert wurde. Dies ist nur vorhanden, wenn „reason“ den Wert „update“ hat.

    • reason

      OnInstalledReason

      Der Grund, warum dieses Ereignis gesendet wird.

onMessage

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

Wird ausgelöst, wenn eine Nachricht von runtime.sendMessage oder tabs.sendMessage gesendet wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

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

  • Nachricht

    beliebig

  • Sender

    MessageSender

  • sendResponse

    Funktion

    Der Parameter sendResponse sieht so aus:

    (response?: any) => void

    • Antwort

      any optional

      Die Antwort, die an den Absender der Nachricht zurückgegeben werden soll.

  • Gibt zurück

    boolean | Promise<any> | undefined

onMessageExternal

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

Wird ausgelöst, wenn eine Nachricht von einer anderen Erweiterung (von runtime.sendMessage) gesendet wird. Kann nicht in einem Inhaltsskript verwendet werden.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

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

  • Nachricht

    beliebig

  • Sender

    MessageSender

  • sendResponse

    Funktion

    Der Parameter sendResponse sieht so aus:

    (response?: any) => void

    • Antwort

      any optional

      Die Antwort, die an den Absender der Nachricht zurückgegeben werden soll.

  • Gibt zurück

    boolean | Promise<any> | undefined

onRestartRequired

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

Wird ausgelöst, wenn eine App oder das Gerät, auf dem sie ausgeführt wird, neu gestartet werden muss. Die App sollte alle ihre Fenster so schnell wie möglich schließen, damit der Neustart erfolgen kann. Wenn die App nichts unternimmt, wird nach einem Kulanzzeitraum von 24 Stunden ein Neustart erzwungen. Derzeit wird dieses Ereignis nur für ChromeOS-Kiosk-Apps ausgelöst.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

onStartup

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

Wird ausgelöst, wenn ein Profil, in dem diese Erweiterung installiert ist, zum ersten Mal gestartet wird. Dieses Ereignis wird nicht ausgelöst, wenn ein Inkognitoprofil gestartet wird, auch wenn diese Erweiterung im Inkognitomodus „split“ ausgeführt wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  () => void

onSuspend

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

Wird kurz vor dem Entladen an die Ereignisseite gesendet. So kann die Erweiterung einige Bereinigungen vornehmen. Da die Seite entladen wird, ist nicht garantiert, dass asynchrone Vorgänge, die während der Verarbeitung dieses Ereignisses gestartet wurden, abgeschlossen werden. Wenn vor dem Entladen weitere Aktivitäten für die Ereignisseite auftreten, wird das Ereignis „onSuspendCanceled“ gesendet und die Seite wird nicht entladen.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  () => void

onSuspendCanceled

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

Wird nach „onSuspend“ gesendet, um anzugeben, dass die App doch nicht entladen wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  () => void

onUpdateAvailable

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

Wird ausgelöst, wenn ein Update verfügbar ist, aber nicht sofort installiert wird, weil die App gerade ausgeführt wird. Wenn Sie nichts unternehmen, wird das Update installiert, wenn die Hintergrundseite das nächste Mal entladen wird. Wenn Sie möchten, dass es früher installiert wird, können Sie „chrome.runtime.reload()“ explizit aufrufen. Wenn Ihre Erweiterung eine persistente Hintergrundseite verwendet, wird die Hintergrundseite natürlich nie entladen. Wenn Sie also „chrome.runtime.reload()“ nicht manuell als Reaktion auf dieses Ereignis aufrufen, wird das Update erst beim nächsten Neustart von Chrome installiert. Wenn keine Handler auf dieses Ereignis warten und Ihre Erweiterung eine persistente Hintergrundseite hat, verhält sie sich so, als ob „chrome.runtime.reload()“ als Reaktion auf dieses Ereignis aufgerufen wird.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (details: object) => void

  • Details

    Objekt

    • Version

      String

      Die Versionsnummer des verfügbaren Updates.