Native Werbebotschaften

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

Host für natives Messaging

Zum Registrieren eines nativen Messaging-Hosts muss die Anwendung eine Manifestdatei installieren, die die Konfiguration des nativen Messaging-Hosts definiert. Hier ein Beispiel für die Manifestdatei:

{
  "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 eine gültige JSON-Datei sein und die folgenden Felder enthalten:

NameBeschreibung
nameName des Hosts für das native Messaging. Clients übergeben diesen String an runtime.connectNative oder runtime.sendNativeMessage. Dieser Name darf nur kleingeschriebene alphanumerische Zeichen, Unterstriche und Punkte enthalten. Der Name darf nicht mit einem Punkt beginnen oder enden und einem Punkt darf kein weiterer Punkt folgen.
descriptionKurze Anwendungsbeschreibung.
pathPfad zum Binärprogramm des Hosts für das native Messaging. Unter Linux und OSX muss der Pfad absolut sein. Unter Windows kann sie relativ zu dem Verzeichnis sein, in dem sich die Manifestdatei befindet. Der Hostprozess wird mit dem aktuellen Verzeichnis gestartet, das auf das Verzeichnis festgelegt ist, das die Host-Binärdatei enthält. Wenn dieser Parameter beispielsweise auf C:\Application\nm_host.exe gesetzt ist, wird er mit dem aktuellen Verzeichnis C:\Application\ gestartet.
typeTyp der Schnittstelle, die für die Kommunikation mit dem nativen Nachrichtenhost verwendet wird. Derzeit ist nur ein Wert für diesen Parameter möglich: stdio. Damit wird festgelegt, dass Chrome stdin und stdout für die Kommunikation mit dem Host verwenden soll.
allowed_originsListe der Erweiterungen, die Zugriff auf den Host für native Nachrichten haben sollen. Platzhalter wie chrome-extension://*/* sind nicht zulässig.

Hoststandort 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. Das App-Installationsprogramm muss den Registrierungsschlüssel 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_ erstellen und den Standardwert dieses Schlüssels auf den vollständigen Pfad zur Manifestdatei festlegen. Verwenden Sie beispielsweise den 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 mithilfe 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 nativen Nachrichtenhosts sucht, wird zuerst die 32-Bit-Registry und dann die 64-Bit-Registry abgefragt.

Unter OS X und Linux variiert der Speicherort der Manifestdatei des nativen Nachrichtenhosts je nach Browser (Google Chrome oder Chromium). Die systemweiten nativen Nachrichtenhosts werden an einem festen Speicherort gesucht. Die Hosts für natives Messaging auf Nutzerebene werden dagegen in einem Unterverzeichnis im Nutzerprofilverzeichnis mit dem Namen NativeMessagingHosts gesucht.

  • OS X (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
  • OS X (nutzerspezifisch, 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 (nutzerspezifischer Standardpfad)
    • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • Chromium: ~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

Natives Messaging-Protokoll

Chrome startet jeden nativen Nachrichtenhost in einem separaten Prozess und kommuniziert mit ihm über Standardeingabe (stdin) und Standardausgabe (stdout). Dasselbe Format wird verwendet, um Nachrichten in beide Richtungen zu senden: Jede Nachricht wird im JSON-Format serialisiert und UTF-8-codiert. Sie erhält eine 32-Bit-Nachrichtenlänge in nativer Bytereihenfolge. Die maximale Größe einer einzelnen Nachricht vom nativen Nachrichtenhost beträgt 1 MB. Dies dient hauptsächlich dazu, Chrome vor fehlerhaften nativen Anwendungen zu schützen. Die maximale Größe der an den nativen Nachrichtenhost gesendeten Nachricht beträgt 4 GB.

Das erste Argument für den nativen Nachrichtenhost ist der Ursprung des Aufrufers, in der Regel chrome-extension://[ID of allowed extension]. Dadurch können Hosts für natives Messaging die Quelle der Nachricht identifizieren, wenn mehrere Erweiterungen im Schlüssel allowed_origins im Hostmanifest für natives Messaging angegeben sind. Warnung: In Windows in Chrome 54 und früheren Versionen wurde der Ursprung als zweiter und nicht als erster Parameter übergeben.

Wenn ein Nachrichtenport mit runtime.connectNative erstellt wird, startet Chrome den nativen Messaging-Hostprozess und läuft weiter, bis der Port gelöscht wird. Wenn eine Nachricht dagegen 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, d.h. Chrome übergibt sie an den Antwort-Callback, der beim Aufruf von runtime.sendNativeMessage angegeben wird. Alle anderen Nachrichten, die in diesem Fall vom nativen Nachrichtenhost generiert wurden, werden ignoriert.

Unter Windows wird dem nativen Nachrichtenhost auch ein Befehlszeilenargument mit einem Handle an das aufrufende native Chrome-Fenster übergeben: --parent-window=<decimal handle value>. Dadurch kann der native Nachrichtenhost native UI-Fenster erstellen, die korrekt übergeordnet sind. Beachten Sie, dass dieser Wert 0 ist, wenn der aufrufende Kontext eine Hintergrundskriptseite ist.

Verbindung zu einer nativen Anwendung herstellen

Das Senden und Empfangen von Nachrichten an und von einer nativen Anwendung ähnelt sehr der erweiterungsübergreifenden Nachrichtenfunktion. Der Hauptunterschied besteht darin, dass runtime.connectNative anstelle von runtime.connect verwendet wird und dass runtime.sendNativeMessage anstelle von runtime.sendMessage verwendet wird. Diese Methoden können nur verwendet werden, wenn die Berechtigung "nativeMessaging" in der Manifestdatei Ihrer App deklariert wurde.

Im folgenden Beispiel wird ein runtime.Port-Objekt erstellt, das mit dem nativen Nachrichtenhost com.my_company.my_application verbunden ist, beginnt das Warten auf Nachrichten von diesem Port und sendet eine ausgehende Nachricht:

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

Mit runtime.sendNativeMessage können Sie eine Nachricht an native Anwendungen senden, ohne einen Port zu erstellen. Beispiel:

chrome.runtime.sendNativeMessage('com.my_company.my_application',
  { text: "Hello" },
  function(response) {
    console.log("Received " + response);
  });

Fehler beim nativen Messaging beheben

Wenn der native Messaging-Host nicht gestartet wird, in stderr schreibt oder gegen das Kommunikationsprotokoll verstößt, wird die Ausgabe in das Fehlerlog von Chrome geschrieben. Unter Linux und OS X können Sie auf dieses Log ganz einfach zugreifen. Starten Sie dazu Chrome über die Befehlszeile und beobachten Sie die Ausgabe im Terminal. Verwenden Sie unter Windows --enable-logging wie unter Protokollierung aktivieren erläutert.

Im Folgenden finden Sie einige Fehler und Tipps zur Lösung der Probleme:

  • Host für natives Messaging konnte nicht gestartet werden.
    • Prüfen Sie, ob Sie die erforderlichen Berechtigungen zum Ausführen der Datei haben.
  • Ungültiger Hostname 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 Pipe zum nativen Nachrichtenhost wurde unterbrochen, bevor die Nachricht von Chrome gelesen wurde. Dieser Vorgang wird wahrscheinlich von Ihrem nativen Nachrichtenhost initiiert.
  • Der angegebene Host für natives Messaging wurde nicht gefunden.
    • Ist der Name in der Erweiterung und in der Manifestdatei richtig geschrieben?
    • Befindet sich das Manifest im richtigen Verzeichnis und mit dem richtigen Namen? Informationen zu den erwarteten Formaten finden Sie unter Hoststandort für natives Messaging.
    • Hat die Manifest-Datei das richtige Format? Ist insbesondere die JSON-Syntax korrekt 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 OS X und Linux müssen sie jedoch absolut sein.
  • Der Hostname des Hosts für das native Messaging ist nicht registriert. (nur Windows)
    • Der Host für natives Messaging wurde in der Windows-Registrierung nicht gefunden. Prüfen Sie mit regedit, ob der Schlüssel wirklich erstellt wurde und dem erforderlichen Format entspricht, wie unter Host für native Nachrichten dokumentiert.
  • 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 nativen Nachrichtenhost.
    • Dies ist ein sehr häufiger Fehler, der auf eine falsche Implementierung des Kommunikationsprotokolls im nativen Messaging-Host hinweist.
    • Achten Sie darauf, dass die gesamte Ausgabe in stdout dem nativen Messaging-Protokoll entspricht. Wenn Sie zu Fehlerbehebungszwecken einige Daten ausgeben möchten, schreiben Sie in stderr.
    • Achten Sie darauf, dass die 32-Bit-Nachrichtenlänge im nativen Ganzzahlformat der Plattform angegeben ist (Little-Endian/Big-Endian).
    • Die Nachrichtenlänge darf 1.024 × 1.024 nicht überschreiten.
    • Die Nachrichtengröße muss der Anzahl von Byte in der Nachricht entsprechen. Diese kann von der "Länge" eines Strings abweichen, 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 Zeilenende im Windows-Stil (\r\n = 0D 0A) ersetzt werden. Der E/A-Modus kann mit __setmode festgelegt werden.