Natives Messaging

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

Host für natives Messaging

Um einen Native Messaging-Host zu registrieren, muss die Anwendung eine Datei speichern, die die Native Messaging-Hostkonfiguration definiert.

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 Native Messaging-Hosts muss ein gültiges JSON-Format haben und die folgenden Felder enthalten:

name

Name des Hosts für natives Messaging. Kunden geben diesen String an runtime.connectNative() oder runtime.sendNativeMessage() weiter. Dieser Name darf nur Kleinbuchstaben, alphanumerische Zeichen, Unterstriche und Punkte enthalten. Der Name darf nicht mit einem Punkt beginnen oder enden und ein Punkt darf nicht auf einen anderen Punkt folgen.

description

Kurze Anwendungsbeschreibung

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 Hostbinä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

Der Typ der Schnittstelle, die für die Kommunikation mit dem nativen Messaging-Host 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.

Speicherort des Hosts für natives Messaging

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

Unter Windows kann sich die Manifestdatei an einer beliebigen Stelle im Dateisystem befinden. Der 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. Beispiel:

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 die folgende .reg-Datei verwenden:

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 nativen Messaging-Hosts sucht, wird zuerst die 32-Bit-Registry und dann die 64-Bit-Registry abgefragt.

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

macOS (systemweit)

Google Chrome: /Library/Google/Chrome/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

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

Chromium: /etc/chromium/native-messaging-hosts/com.my_company.my_application.json

Linux (nutzerspezifisch, default-Pfad)

Google Chrome: ~/.config/google-chrome/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 nativen Messaging-Host in einem separaten Prozess und kommuniziert mit ihm über die Standardeingabe (stdin) und die Standardausgabe (stdout). Das gleiche Format wird zum Senden von Nachrichten in beide Richtungen verwendet. Jede Nachricht wird mit JSON serialisiert, UTF-8-codiert und durch eine 32-Bit-Nachrichtenlänge in nativer Byte-Reihenfolge eingeleitet. Die maximale Größe einer einzelnen Nachricht vom nativen Messaging-Host 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 nativen Messaging-Host gesendet wird, beträgt 4 GB.

Das erste Argument für den nativen Messaging-Host ist der Ursprung des Anrufers, in der Regel chrome-extension://[ID of allowed extension]. So können Hosts für natives Messaging die Quelle der Nachricht ermitteln, wenn im Schlüssel allowed_origins 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 an das native Chrome-Fenster übergeben, das die Funktion aufruft: --parent-window=<decimal handle value>. Dadurch kann der Host für native Mitteilungen native UI-Fenster erstellen, denen das richtige übergeordnete Element zugewiesen ist. Hinweis: Dieser Wert ist 0, wenn der Aufrufkontext ein Dienstworker ist.

Wenn ein Nachrichten-Port mit runtime.connectNative() erstellt wird, startet Chrome den nativen Messaging-Hostprozess und hält ihn so lange am Laufen, bis der Port gelöscht wird. Wenn eine Nachricht hingegen mit runtime.sendNativeMessage() gesendet wird, ohne einen Messaging-Port zu erstellen, startet Chrome für jede Nachricht einen neuen nativen Messaging-Hostprozess. In diesem Fall wird die erste vom Hostprozess generierte Nachricht als Antwort auf die ursprüngliche Anfrage verarbeitet und Chrome gibt sie an den Antwort-Callback weiter, der beim Aufruf von runtime.sendNativeMessage() angegeben wurde. Alle anderen vom nativen Nachrichtenhost generierten Nachrichten werden in diesem Fall ignoriert.

Verbindung zu einer nativen Anwendung herstellen

Das Senden und Empfangen von Nachrichten an und von einer nativen Anwendung funktioniert ähnlich wie erweiterungsübergreifende Nachrichten. Der Hauptunterschied besteht darin, dass runtime.connectNative() anstelle von runtime.connect() und runtime.sendNativeMessage() anstelle von runtime.sendMessage() verwendet wird.

Wenn Sie diese Methoden verwenden möchten, muss die Berechtigung „nativeMessaging“ in der Manifestdatei Ihrer Erweiterung deklariert werden.

Diese Methoden sind nicht innerhalb von Inhaltsskripts verfügbar, sondern nur innerhalb der Seiten und des Service Workers Ihrer Erweiterung. Wenn Sie von einem Inhaltsskript 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 nativen Messaging-Host com.my_company.my_application verbunden ist. Es wird dann damit begonnen, nach Nachrichten von diesem Port zu suchen, und eine ausgehende Nachricht wird gesendet:

var port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener(function (msg) {
  console.log('Received' + msg);
});
port.onDisconnect.addListener(function () {
  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'},
  function (response) {
    console.log('Received ' + response);
  }
);

Natives Messaging debuggen

Wenn bestimmte Fehler bei der nativen Nachrichtenübermittlung auftreten, wird die Ausgabe in das Fehlerprotokoll von Chrome geschrieben. Dazu gehört auch, wenn der Host für natives Messaging nicht gestartet wird, auf stderr schreibt oder gegen das Kommunikationsprotokoll verstößt. Unter Linux und macOS können Sie auf dieses Protokoll zugreifen, indem Sie Chrome über die Befehlszeile starten und die Ausgabe im Terminal beobachten. Verwenden Sie unter Windows --enable-logging, wie unter Logging aktivieren beschrieben.

Im Folgenden finden Sie einige häufige Fehler und Tipps zu deren Behebung:

Der native Messaging-Host konnte nicht gestartet werden.

Prüfen Sie, ob Sie die erforderlichen Berechtigungen zum Ausführen der Hostdatei für natives Messaging haben.

Ungültiger Hostname für natives Messaging angegeben.

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

Der native Host wurde verlassen.

Die Verbindung zum nativen Messaging-Host war unterbrochen, bevor die Nachricht von Chrome gelesen wurde. Dies wird höchstwahrscheinlich von Ihrem Native Messaging-Host 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?
• Befindet sich das Manifest im richtigen Verzeichnis und hat es den richtigen Namen? Die erwarteten Formate finden Sie unter Speicherort des nativen Messaging-Hosts.
• Hat die Manifestdatei das richtige Format? Ist das JSON-Objekt insbesondere gültig und wohlgeformt und stimmen die Werte mit der Definition eines Manifests für einen nativen Messaging-Host überein?
• 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 Hostname des Hosts für natives Messaging ist nicht registriert. (nur Windows)