chrome.runtime

Beschreibung

Mit der chrome.runtime API können Sie den Service Worker abrufen, Details zum Manifest zurückgeben und auf Ereignisse im Lebenszyklus der Erweiterung warten und darauf reagieren. Mit dieser API können Sie auch den relativen Pfad von URLs in vollständig qualifizierte URLs umwandeln.

Übersicht

Die Runtime API bietet Methoden zur Unterstützung einer Reihe von Funktionen, die von Ihren Erweiterungen verwendet werden können:

Nachrichtenübermittlung
Ihre Erweiterung kann mit verschiedenen Kontexten innerhalb Ihrer Erweiterung und auch mit anderen Erweiterungen kommunizieren. Dazu werden die folgenden Methoden und Ereignisse verwendet: connect(), onConnect, onConnectExternal, sendMessage(), onMessage und onMessageExternal. Außerdem kann Ihre Erweiterung Nachrichten mithilfe von connectNative() und sendNativeMessage() an native Anwendungen auf dem Gerät des Nutzers übergeben.
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 Meta-Vorgänge für die Erweiterung ausführen und die Optionsseite anzeigen. Methoden und Ereignisse in dieser Kategorie sind unter anderem onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck() und setUninstallURL().
Hilfsprogramme
Diese Methoden bieten Funktionen wie die Konvertierung interner Ressourcendarstellungen in externe Formate. Zu den Methoden in dieser Kategorie gehört getURL().
Kioskmodus-Dienstprogramme
Diese Methoden sind nur unter ChromeOS verfügbar und dienen hauptsächlich zur Unterstützung von Kioskimplementierungen. Zu den Methoden in dieser Kategorie gehören restart und restartAfterDelay.

Berechtigungen

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

Manifest

Das folgende Beispiel zeigt, wie die Berechtigung nativeMessaging im Manifest deklariert wird:

manifest.json:

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

Anwendungsfälle

Bild auf einer Webseite einfü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 webzugängliche Ressourcen verfügbar gemacht werden müssen und dass in der Regel Inhaltsskripte für das Einfügen von Erweiterungs-Assets verantwortlich sind.

In diesem Beispiel fügt die Erweiterung logo.png der Seite hinzu, in die das Inhaltsscript eingefügt wird. Dazu wird runtime.getURL() verwendet, um eine vollständig qualifizierte URL zu erstellen. Zuerst muss das Asset jedoch im Manifest als webzugä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 Content-Script senden

Es ist üblich, dass die Content-Scripts einer Erweiterung Daten benötigen, die von einem anderen Teil der Erweiterung, z. B. dem Service Worker, verwaltet werden. Ähnlich wie bei zwei Browserfenstern, die auf dieselbe Webseite geöffnet sind, können diese beiden Kontexte nicht direkt auf die Werte des jeweils anderen zugreifen. Stattdessen kann die Erweiterung Nachrichtenübermittlung verwenden, um die verschiedenen Kontexte zu koordinieren.

In diesem Beispiel benötigt das Content-Script einige Daten vom Service Worker der Erweiterung, um die Benutzeroberfläche zu initialisieren. Dazu wird eine get-user-data-Nachricht an den Service Worker gesendet, 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 ihren Nutzern besser dienen und die Nutzerbindung verbessern kann. 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 Manifest V3-Demo für webzugängliche Ressourcen.

Typen

ContextFilter

Chrome 114 und höher

Ein Filter, der mit bestimmten Erweiterungskontexten abgeglichen wird. Übereinstimmende Kontexte müssen allen angegebenen Filtern entsprechen. Jeder Filter, der nicht angegeben ist, entspricht allen verfügbaren Kontexten. Ein Filter mit dem Wert `{}` 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

    boolean optional

  • tabIds

    number[] optional

  • windowIds

    number[] optional

ContextType

Chrome 114 und höher

Enum

„TAB“
Gibt den Kontexttyp als Tab an

„POPUP“
Gibt den Kontexttyp als Erweiterungs-Pop-up-Fenster 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 und höher

Ein Kontext, in dem Erweiterungsinhalte gehostet werden.

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 diesem Kontext zugeordnet 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 auf 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.

MessageSender

Ein Objekt mit Informationen zum Skriptkontext, über den eine Nachricht oder Anfrage gesendet wurde.

Attribute

  • documentId

    String optional

    Chrome 106 und höher

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

  • documentLifecycle

    String optional

    Chrome 106 und höher

    Der Lebenszyklus des Dokuments, mit dem die Verbindung geöffnet wurde, 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 und höher

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

  • origin

    String optional

    Chrome 80 und höher

    Der Ursprung der Seite oder des Frames, über die die Verbindung geöffnet wurde. Sie kann von der URL-Eigenschaft abweichen (z.B. „about:blank“) oder undurchsichtig sein (z.B. Sandboxed-iFrames). Das ist nützlich, um festzustellen, ob der Ursprung 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 Content-Scripts) geöffnet wurde, und nur, wenn der Empfänger eine Erweiterung und keine App ist.

  • tlsChannelId

    String optional

    Die TLS-Channel-ID der Seite oder des Frames, über die 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 die Verbindung geöffnet wurde. Wenn sich der Absender in einem iFrame befindet, wird die URL des iFrames und nicht die URL der Seite, auf der er gehostet wird, zurückgegeben.

OnInstalledReason

Chrome 44 und höher

Der Grund, warum dieses Ereignis gesendet wird.

Enum

„install“
Gibt den Ereignisgrund als Installation an.

„update“
Gibt den Ereignisgrund als Erweiterungsaktualisierung an.

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

"shared_module_update"
Gibt den Grund für das Ereignis als Aktualisierung eines freigegebenen Moduls an.

OnRestartRequiredReason

Chrome 44 und 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 wurde. „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 Ereignisgrund als Update der App an.

„os_update“
Gibt den Ereignisgrund als Update des Betriebssystems an.

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

PlatformArch

Chrome 44 und 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

  • Bogen

    PlatformArch

    Die Prozessorarchitektur der Maschine.

  • nacl_arch

    PlatformNaclArch optional

    Die Architektur des nativen Clients. Dies kann sich auf einigen Plattformen von „arch“ unterscheiden.

  • Das Betriebssystem, auf dem Chrome ausgeführt wird.

PlatformNaclArch

Chrome 44 und höher

Die Architektur des nativen Clients. Dies kann sich auf einigen Plattformen von „arch“ unterscheiden.

Enum

arm
Gibt die native Clientarchitektur als „arm“ an.

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

„x86-64“
Gibt die native Clientarchitektur als x86-64 an.

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

„mips64“
Gibt die native Clientarchitektur als „mips64“ an.

PlatformOs

Chrome 44 und höher

Das Betriebssystem, auf dem Chrome ausgeführt wird.

Enum

„mac“
Gibt das MacOS-Betriebssystem 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 Lang andauernde Verbindungen.

Attribute

  • name

    String

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

  • onDisconnect

    Event<functionvoidvoid>

    Wird ausgelöst, wenn die Verbindung des Ports zum anderen Ende bzw. zu den anderen Enden getrennt wird. runtime.lastError kann festgelegt werden, wenn der Anschluss 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 onDisconnect.addListener-Funktion sieht so aus: 

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

    • callback

      Funktion

      Der Parameter callback sieht so aus: 

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

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

    Die onMessage.addListener-Funktion sieht so aus: 

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

    • callback

      Funktion

      Der Parameter callback sieht so aus: 

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

      • Nachricht

        beliebig

      • Port

        Port

  • Absender

    MessageSender optional

    Dieses Attribut ist nur für Ports vorhanden, die an die Listener onConnect, onConnectExternal und onConnectNative übergeben werden.

  • Verknüpfung aufheben

    void

    Trennen Sie den Port sofort. Wenn disconnect() für einen bereits getrennten Port aufgerufen wird, hat das keine Auswirkungen. Wenn ein Port getrennt wird, werden keine neuen Ereignisse an diesen Port gesendet.

    Die disconnect-Funktion sieht so aus: 

    () => {...}

  • postMessage

    void

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

    Die postMessage-Funktion sieht so aus: 

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

    • Nachricht

      beliebig

      Chrome 52 und höher

      Die zu sendende Nachricht. Dieses Objekt sollte in JSON konvertierbar sein.

RequestUpdateCheckStatus

Chrome 44 und höher

Ergebnis der Update-Prüfung.

Enum

„throttled“
Gibt an, dass die Statusprüfung gedrosselt wurde. Dies kann nach wiederholten Prüfungen innerhalb kurzer Zeit auftreten.

„no_update“
Gibt an, dass keine verfügbaren Updates installiert werden können.

„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 gefüllt, wenn der Aufruf einer API-Funktion fehlschlägt. Andernfalls ist der Wert „undefined“. Sie ist nur im Bereich des Callbacks dieser Funktion definiert. Wenn ein Fehler auftritt, aber nicht auf runtime.lastError innerhalb des Rückrufs zugegriffen wird, wird eine Meldung in der Konsole protokolliert, in der die API-Funktion aufgeführt ist, die den Fehler verursacht hat. Bei API-Funktionen, die Promises zurückgeben, wird diese Eigenschaft nicht festgelegt.

Typ

Objekt

Attribute

  • Nachricht

    String optional

    Details zum aufgetretenen Fehler.

Methoden

connect()

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

Es wird versucht, Listener innerhalb einer Erweiterung (z. B. der Hintergrundseite) oder anderer Erweiterungen/Apps zu verbinden. Das ist nützlich für Inhaltsscripts, die eine Verbindung zu ihren Erweiterungsprozessen herstellen, für die Kommunikation zwischen Apps/Erweiterungen und für Web Messaging. Es wird keine Verbindung zu Listenern in einem Content-Script hergestellt. Erweiterungen können über tabs.connect eine Verbindung zu Inhaltsskripten herstellen, die in Tabs eingebettet sind.

Parameter

  • extensionId

    String optional

    Die ID der Erweiterung, mit der eine Verbindung hergestellt werden soll. Wird kein Wert angegeben, wird versucht, eine Verbindung mit Ihrer eigenen Erweiterung herzustellen. Erforderlich, wenn Nachrichten von einer Webseite für Web Messaging gesendet werden.

  • connectInfo

    object optional

    • includeTlsChannelId

      boolean optional

      Gibt an, ob die TLS-Channel-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, ü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, ü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>

Hintergrundseiten gibt es in MV3-Erweiterungen nicht.

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 vom System geladen, bevor der Callback aufgerufen wird. Wenn keine Hintergrundseite vorhanden ist, wird ein Fehler ausgegeben.

Parameter

  • callback

    Funktion 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 und 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 Manifest-Datei.

Ausgabe

  • Objekt

    Die Manifestdetails.

getPackageDirectoryEntry()

Zusicherung Nur im Vordergrund 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
): Promise<DirectoryEntry>

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

Ausgabe

  • Promise<DirectoryEntry>

    Chrome 122 und 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

    Funktion optional

    Der Parameter callback sieht so aus: 

    (platformInfo: PlatformInfo) => void

Ausgabe

  • Promise<PlatformInfo>

    Chrome 99 und höher

    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 in einem Installationsverzeichnis für Apps/Erweiterungen in eine vollständig qualifizierte URL.

Parameter

  • Pfad

    String

    Ein Pfad zu einer Ressource in einer App/Erweiterung, der relativ zum Installationsverzeichnis angegeben wird.

Ausgabe

  • String

    Die vollständig qualifizierte URL der Ressource.

openOptionsPage()

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

Öffnen Sie die Optionenseite der Erweiterung, falls möglich.

Das genaue Verhalten kann vom options_ui- oder options_page-Schlüssel Ihres Manifests oder davon abhängen, was Chrome zu diesem Zeitpunkt unterstützt. Die Seite kann beispielsweise in einem neuen Tab, in chrome://extensions, in einer App oder auf einer geöffneten Optionsseite geöffnet werden. Die Seite des Aufrufers wird dadurch nie neu geladen.

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 99 und 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 Überprüfung auf Updates 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 runtime.onUpdateAvailable-Ereignis 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 Client-Erweiterungsversion sehr veraltet ist, und Sie einen Nutzer auffordern möchten, die Erweiterung zu aktualisieren. Die meisten anderen Verwendungszwecke von requestUpdateCheck, z. B. der bedingungslose Aufruf basierend auf einem sich wiederholenden Timer, führen wahrscheinlich nur zu einer Verschwendung von Client-, Netzwerk- und Serverressourcen.

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: object) => void

    • Ergebnis

      Objekt

      Chrome 109 und höher

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

      • Ergebnis der Update-Prüfung.

      • Version

        String optional

        Wenn ein Update verfügbar ist, enthält dieser Parameter 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 nichts unternommen.

restartAfterDelay()

Promise Chrome 53 und höher 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
): Promise<void>

Das ChromeOS-Gerät wird neu gestartet, wenn die App nach der angegebenen Anzahl von Sekunden im Kioskmodus ausgeführt wird. Wenn der Befehl vor Ablauf der Zeit noch einmal aufgerufen wird, wird der Neustart verzögert. Wenn die Funktion mit dem Wert -1 aufgerufen wird, wird der Neustart abgebrochen. In anderen Modi als dem Kioskmodus hat sie keine Auswirkungen. Sie darf nur wiederholt von der ersten Erweiterung aufgerufen werden, um diese API aufzurufen.

Parameter

  • Sekunden

    Zahl

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 99 und höher

    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 Event-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 Ihre Erweiterung gesendet wird, wird das Ereignis runtime.onMessage in jedem Frame Ihrer Erweiterung (außer im Frame des Absenders) ausgelöst. Bei einer anderen Erweiterung wird runtime.onMessageExternal ausgelöst. Hinweis: Erweiterungen können mit dieser Methode keine Nachrichten an Content-Scripts senden. 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 dieser Parameter fehlt, wird die Nachricht an Ihre eigene Erweiterung/App gesendet. Er ist 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

    object optional

    • includeTlsChannelId

      boolean optional

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

  • callback

    Funktion optional

    Chrome 99 und 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 einer 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 und höher

    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.

  • Nachricht

    Objekt

    Die Nachricht, die an den nativen Messaging-Host übergeben wird.

  • callback

    Funktion optional

    Chrome 99 und höher

    Der Parameter callback sieht so aus: 

    (response: any) => void

    • Antwort

      beliebig

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

Ausgabe

  • Promise<any>

    Chrome 99 und 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 beim Deinstallieren aufgerufen werden soll. Das kann zum Bereinigen serverseitiger Daten, für Analysen und zum Implementieren von Umfragen verwendet werden. Maximal 1.023 Zeichen.

Parameter

  • URL

    String

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

  • callback

    Funktion optional

    Chrome 45 und höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 99 und höher

    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,
)

Verwenden Sie runtime.onRestartRequired.

Wird ausgelöst, wenn ein Chrome-Update verfügbar ist, aber nicht sofort installiert wird, da ein Neustart des Browsers 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 Inhaltsscript (durch runtime.connect) hergestellt wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (port: Port) => void

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

onConnectNative

Chrome 76 und 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

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 des freigegebenen Moduls an, die aktualisiert wurde. Dies ist nur vorhanden, wenn „reason“ „shared_module_update“ ist.

      • previousVersion

        String optional

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

      • Der Grund, warum dieses Ereignis gesendet wird.

onMessage

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

Wird ausgelöst, wenn eine Nachricht entweder von einem Erweiterungsprozess (durch runtime.sendMessage) oder von einem Inhaltsscript (durch tabs.sendMessage) gesendet wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | undefined

onMessageExternal

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

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

    • Nachricht

      beliebig

    • Absender

      MessageSender

    • sendResponse

      Funktion

      Der Parameter sendResponse sieht so aus: 

      () => void

    • Gibt zurück

      boolean | 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 zum frühestmöglichen Zeitpunkt schließen, damit der Neustart erfolgen kann. Wenn die App nichts tut, wird nach Ablauf einer 24-stündigen Kulanzfrist ein Neustart erzwungen. Derzeit wird dieses Ereignis nur für ChromeOS-Kiosk-Apps ausgelöst.

Parameter

onStartup

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

Wird ausgelöst, wenn ein Profil, auf 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 „Geteilt“ ausgeführt wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    () => void

onSuspend

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

Wird an die Ereignisseite gesendet, kurz bevor sie entladen wird. So hat die Erweiterung die Möglichkeit, einige Bereinigungen vorzunehmen. Da die Seite entladen wird, werden alle asynchronen Vorgänge, die während der Verarbeitung dieses Ereignisses gestartet werden, möglicherweise nicht abgeschlossen. Wenn vor dem Entladen der Ereignisseite weitere Aktivitäten stattfinden, 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 beim nächsten Entladen der Hintergrundseite installiert. Wenn Sie möchten, dass es früher installiert wird, können Sie explizit chrome.runtime.reload() aufrufen. Wenn Ihre Erweiterung eine persistente Hintergrundseite verwendet, wird die Hintergrundseite natürlich nie entladen. Wenn Sie also nicht als Reaktion auf dieses Ereignis manuell chrome.runtime.reload() 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.