Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Natives Messaging

Erweiterungen können Nachrichten mit nativen Anwendungen über eine API austauschen, die den anderen APIs für die Nachrichtenübergabe ähnelt. Native Anwendungen, die diese Funktion unterstützen, müssen einen Host für natives Messaging registrieren, der mit der Erweiterung kommunizieren kann. Chrome startet den Host in einem separaten Prozess und kommuniziert mit ihm über Standard-Ein- und Ausgabestreams.

Host für natives Messaging

Um einen Host für natives Messaging zu registrieren, muss die Anwendung eine Datei speichern, in der die Konfiguration des Hosts für natives Messaging definiert ist.

Hier ein Beispiel für die Datei:

{
  "name": "com.my_company.my_application",
  "description": "My Application",
  "path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"]
}

Die Manifestdatei des Hosts für natives Messaging muss gültiges JSON enthalten und die folgenden Felder aufweisen:

name: Name des Hosts für natives Messaging. Clients übergeben diesen String an runtime.connectNative() oder runtime.sendNativeMessage(). Dieser Name darf nur alphanumerische Kleinbuchstaben, Unterstriche und Punkte enthalten. Der Name darf nicht mit einem Punkt beginnen oder enden und auf einen Punkt darf kein weiterer Punkt folgen.
description: Kurze Beschreibung der Anwendung
path: Pfad zur Binärdatei des Hosts für natives Messaging. Unter Linux und macOS muss der Pfad absolut sein. Unter Windows kann er relativ zum Verzeichnis sein, das die Manifestdatei enthält. Der Hostprozess wird gestartet, wobei das aktuelle Verzeichnis auf das Verzeichnis festgelegt ist, das die Host-Binärdatei enthält. Wenn dieser Parameter beispielsweise auf C:\Application\nm_host.exe festgelegt ist, wird er mit dem aktuellen Verzeichnis „C:\Application“ gestartet.
type: Typ der Schnittstelle, die für die Kommunikation mit dem Host für natives Messaging verwendet wird. Dieser Parameter hat einen möglichen Wert: stdio. Es gibt an, dass Chrome stdin und stdout für die Kommunikation mit dem Host verwenden soll.
allowed_origins: Liste der Erweiterungen, die Zugriff auf den Host für natives Messaging haben sollen. allowed_origins-Werte dürfen keine Platzhalter enthalten.

Standort des Hosts für natives Messaging

Der Speicherort der Manifestdatei hängt von der Plattform ab.

Unter Windows kann sich die Manifestdatei an einem beliebigen Ort im Dateisystem befinden. Das Installationsprogramm der Anwendung muss einen Registrierungsschlüssel erstellen, entweder HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application oder HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, und den Standardwert dieses Schlüssels auf den vollständigen Pfad zur Manifestdatei festlegen. Zum Beispiel mit dem folgenden Befehl:

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

oder mit der folgenden .reg-Datei:

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"

Wenn Chrome nach Hosts für die native Nachrichtenübermittlung sucht, wird zuerst die 32‑Bit-Registrierung und dann die 64‑Bit-Registrierung abgefragt.

Unter macOS und Linux variiert der Speicherort der Manifestdatei des nativen Messaging-Hosts je nach Browser (Google Chrome, Google Chrome for Testing oder Chromium). Die systemweiten Hosts für natives Messaging werden an einem festen Speicherort gesucht, während die Hosts für natives Messaging auf Nutzerebene im Unterverzeichnis NativeMessagingHosts/ des Nutzerprofilverzeichnisses gesucht werden.

macOS (systemweit): Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: /Library/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: /Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
macOS (nutzerspezifischer Standardpfad): Google Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: ~/Library/Application Support/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
Linux (systemweit): Google Chrome: /etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json; Google Chrome for Testing: /etc/opt/chrome_for_testing/native-messaging-hosts/com.my_company.my_application.json; Chromium: /etc/chromium/native-messaging-hosts/com.my_company.my_application.json
Linux (nutzerspezifischer Standardpfad): Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: ~/.config/google-chrome-for-testing/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Protokoll für natives Messaging

Chrome startet jeden Host für natives Messaging in einem separaten Prozess und kommuniziert mit ihm über die Standardeingabe (stdin) und die Standardausgabe (stdout). Für das Senden von Nachrichten in beide Richtungen wird dasselbe Format verwendet. Jede Nachricht wird mit JSON serialisiert, UTF-8-codiert und mit einer 32-Bit-Nachrichtenlänge in nativer Byte-Reihenfolge versehen. Die maximale Größe einer einzelnen Nachricht vom Host für die native Nachrichtenübermittlung beträgt 1 MB. Dies dient hauptsächlich dazu, Chrome vor fehlerhaften nativen Anwendungen zu schützen. Die maximale Größe der Nachricht, die an den Host für natives Messaging gesendet wird, beträgt 64 MiB.

Das erste Argument für den Host für natives Messaging ist der Ursprung des Aufrufers, in der Regel chrome-extension://[ID of allowed extension]. So können Hosts für natives Messaging die Quelle der Nachricht identifizieren, wenn im allowed_origins-Schlüssel im Manifest des Hosts für natives Messaging mehrere Erweiterungen angegeben sind.

Unter Windows wird dem Host für natives Messaging auch ein Befehlszeilenargument mit einem Handle für das aufrufende native Chrome-Fenster übergeben: --parent-window=<decimal handle value>. So kann der Host für natives Messaging Fenster für die native Benutzeroberfläche erstellen, die korrekt übergeordnet sind. Beachten Sie, dass dieser Wert 0 ist, wenn der aufrufende Kontext ein Service Worker ist.

Wenn ein Nachrichtenport mit runtime.connectNative() erstellt wird, startet Chrome einen nativen Messaging-Hostprozess und führt ihn aus, bis der Port zerstört wird. Wenn eine Nachricht mit runtime.sendNativeMessage() gesendet wird, ohne dass ein Messaging-Port erstellt wird, startet Chrome für jede Nachricht einen neuen Prozess für den Host für natives Messaging. In diesem Fall wird die erste vom Hostprozess generierte Nachricht als Antwort auf die ursprüngliche Anfrage behandelt und von Chrome an den Antwort-Callback übergeben, der beim Aufrufen von runtime.sendNativeMessage() angegeben wurde. Alle anderen Nachrichten, die vom Host für natives Messaging in diesem Fall generiert werden, werden ignoriert.

Verbindung zu einer nativen Anwendung herstellen

Das Senden und Empfangen von Nachrichten an und von einer nativen Anwendung ähnelt sehr dem Senden von Nachrichten zwischen Erweiterungen. Der Hauptunterschied besteht darin, dass runtime.connectNative() anstelle von runtime.connect() und runtime.sendNativeMessage() anstelle von runtime.sendMessage() verwendet wird.

Damit Sie diese Methoden verwenden können, muss die Berechtigung „nativeMessaging“ in der Manifestdatei Ihrer Erweiterung deklariert werden.

Diese Methoden sind nicht in Inhaltsskripts, sondern nur auf den Seiten und im Service Worker Ihrer Erweiterung verfügbar. Wenn Sie von einem Content-Script aus mit der nativen Anwendung kommunizieren möchten, senden Sie die Nachricht an Ihren Service Worker, damit er sie an die native Anwendung weiterleitet.

Im folgenden Beispiel wird ein runtime.Port-Objekt erstellt, das mit dem Host für natives Messaging com.my_company.my_application verbunden ist. Es beginnt, Nachrichten von diesem Port zu empfangen, und sendet eine ausgehende Nachricht:

const port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener((msg) => {
  console.log('Received', msg);
});
port.onDisconnect.addListener(() => {
  if (chrome.runtime.lastError) {
    console.error(
      'Disconnected due to error:',
      chrome.runtime.lastError.message
    );
  } else {
    console.log('Disconnected');
  }
});
port.postMessage({text: 'Hello, my_application'});

Verwenden Sie runtime.sendNativeMessage, um eine Nachricht an die native Anwendung zu senden, ohne einen Port zu erstellen, z.B.:

chrome.runtime.sendNativeMessage(
  'com.my_company.my_application',
  {text: 'Hello'},
  (response) => {
    if (chrome.runtime.lastError) {
      console.error(
        'Error sending native message:',
        chrome.runtime.lastError.message
      );
      return;
    }
    console.log('Received', response);
  }
);

Fehlerbehebung bei nativem Messaging

Wenn Fehler bei der nativen Nachrichtenübermittlung auftreten, wird die Diagnoseausgabe in das Fehlerlog von Chrome geschrieben.

Linux und macOS

# Linux
google-chrome --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

Windows

Starten Sie Chrome mit aktivierter Protokollierung:

chrome.exe --enable-logging --log-level=1

Übergeben Sie --user-data-dir="%TEMP%\nm-debug", um eine separate Instanz zu starten, ohne an einen vorhandenen Chrome-Prozess anzuhängen.

So sehen Sie die Ausgabe: Streamen Sie chrome_debug.log mit PowerShell:

$log = "$env:LOCALAPPDATA\Google\Chrome\User Data\chrome_debug.log"
Get-Content -Wait $log | Select-String "native_messag|launch_context"

Sie können chrome_debug.log auch in einem Texteditor öffnen und nach launch_context.cc oder native_message_process_host.cc suchen.

Wichtige Details zur Protokollierung

Fehler beim Suchen und Parsen von Manifesten in launch_context.cc werden als Warnungen protokolliert. Verwenden Sie --log-level=1 anstelle von 2 (ERROR), um diese Startdiagnosen zu unterdrücken.
Suchen Sie nach launch_context, um Manifest- und binäre Startfehler zu finden, und nach native_messag, um Fehler bei der Nutzlastgröße und der Pipe-Kommunikation zu finden.

Häufige Fehler

Im Folgenden finden Sie einige häufige Fehler und Tipps zur Fehlerbehebung:

Fehler beim Starten des Hosts für natives Messaging.

Prüfen Sie, ob Sie über ausreichende Berechtigungen zum Ausführen der Hostdatei für natives Messaging verfügen.

Ungültiger Host für natives Messaging angegeben.

Prüfen Sie, ob der Name ungültige Zeichen enthält. Es sind nur alphanumerische Zeichen in Kleinschreibung, Unterstriche und Punkte zulässig. Ein Name darf nicht mit einem Punkt beginnen oder enden und auf einen Punkt darf kein weiterer Punkt folgen.

Der native Host wurde beendet.

Die Verbindung zum Host für natives Messaging wurde unterbrochen, bevor die Nachricht von Chrome gelesen wurde. Das wird höchstwahrscheinlich von Ihrem Host für natives Messaging initiiert.

Der angegebene Host für natives Messaging wurde nicht gefunden.

Dann machen Sie Folgendes:

Ist der Name in der Erweiterung und in der Manifestdatei richtig geschrieben?
Ist der Registrierungsschlüssel unter HKEY_CURRENT_USER oder HKEY_LOCAL_MACHINE vorhanden und verweist sein Standardwert auf den vollständigen Manifestpfad? Chrome fragt zuerst die 32‑Bit-Registrierungsansicht und dann die 64‑Bit-Ansicht ab. Verwenden Sie regedit, um den Schlüssel zu überprüfen. Standort des Hosts für natives Messaging
Befindet sich die Manifestdatei unter macOS und Linux im erwarteten Verzeichnis und ist nach dem Host benannt (z. B. com.my_company.my_application.json)? Weitere Informationen finden Sie unter Speicherort des Hosts für natives Messaging.
Hat die Manifestdatei das richtige Format? Insbesondere wird geprüft, ob das JSON-Dokument gültig und wohlgeformt ist und ob die Werte der Definition eines Manifests für den Host für natives Messaging entsprechen.
Ist die in path angegebene Datei vorhanden? Unter Windows können Pfade relativ sein, unter macOS und Linux müssen sie jedoch absolut sein.

Der Zugriff auf den angegebenen Host für natives Messaging ist verboten.

Ist der Ursprung der Erweiterung in allowed_origins aufgeführt?

Fehler bei der Kommunikation mit dem Host für natives Messaging.

Dies weist auf eine falsche Implementierung des Kommunikationsprotokolls im Host für natives Messaging hin.

Achten Sie darauf, dass die gesamte Ausgabe in stdout dem nativen Messaging-Protokoll entspricht. Wenn Sie einige Daten zu Debugging-Zwecken ausgeben möchten, schreiben Sie in stderr.
Die 32-Bit-Nachrichtenlänge muss im nativen Ganzzahlformat der Plattform (Little-Endian/Big-Endian) vorliegen.
Die Nachrichtenlänge darf 1024*1024 nicht überschreiten.
Die Nachrichtengröße muss der Anzahl der Byte in der Nachricht entsprechen. Das kann sich von der „Länge“ eines Strings unterscheiden, da Zeichen durch mehrere Byte dargestellt werden können.
Nur Windows:Der E/A-Modus des Programms muss auf O_BINARY eingestellt sein. Standardmäßig ist der E/A-Modus O_TEXT, wodurch das Nachrichtenformat beschädigt wird, da Zeilenumbrüche (\n = 0A) durch Windows-Zeilenenden (\r\n = 0D 0A) ersetzt werden. Der E/A-Modus kann mit __setmode festgelegt werden.