Deze pagina is vertaald door de Cloud Translation API.

Native berichten

Extensies kunnen berichten uitwisselen met native applicaties via een API die vergelijkbaar is met andere API's voor berichtuitwisseling . Native applicaties die deze functie ondersteunen, moeten een native berichtenhost registreren die met de extensie kan communiceren. Chrome start de host in een apart proces en communiceert ermee via standaardinvoer- en standaarduitvoerstreams.

Native berichtenhost

Om een native berichtenhost te registreren, moet de applicatie een bestand opslaan waarin de configuratie van de native berichtenhost is gedefinieerd.

Een voorbeeld van het bestand ziet er als volgt uit:

{
  "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/"]
}

Het manifestbestand van de native berichtenhost moet geldige JSON zijn en de volgende velden bevatten:

name: De naam van de native berichtenhost. Clients geven deze tekenreeks door aan runtime.connectNative() of runtime.sendNativeMessage() . Deze naam mag alleen kleine letters, cijfers, underscores en punten bevatten. De naam mag niet beginnen of eindigen met een punt, en een punt mag niet gevolgd worden door een andere punt.
description: Korte beschrijving van de applicatie.
path: Pad naar het binaire bestand van de native berichtenhost. Op Linux en macOS moet het pad absoluut zijn. Op Windows kan het relatief zijn ten opzichte van de map waarin het manifestbestand zich bevindt. Het hostproces wordt gestart met de huidige map ingesteld op de map die het hostbinaire bestand bevat. Als deze parameter bijvoorbeeld is ingesteld op C:\Application\nm_host.exe , wordt het gestart met de huidige map `C:\Application`.
type: Het type interface dat wordt gebruikt om te communiceren met de native berichtenhost. Deze parameter heeft één mogelijke waarde: stdio . Dit geeft aan dat Chrome stdin en stdout moet gebruiken om met de host te communiceren.
allowed_origins: Lijst met extensies die toegang moeten hebben tot de native berichtenhost. Waarden voor allowed_origins mogen geen wildcards bevatten.

Native messaging hostlocatie

De locatie van het manifestbestand is afhankelijk van het platform.

Op Windows kan het manifestbestand zich overal in het bestandssysteem bevinden. Het installatieprogramma van de applicatie moet een registersleutel aanmaken, ofwel HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application of HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application , en de standaardwaarde van die sleutel instellen op het volledige pad naar het manifestbestand. Bijvoorbeeld met behulp van de volgende opdracht:

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

of door gebruik te maken van het volgende .reg -bestand:

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

Wanneer Chrome zoekt naar native berichtenhosts, wordt eerst het 32-bits register geraadpleegd en vervolgens het 64-bits register.

Op macOS en Linux verschilt de locatie van het manifestbestand van de native messaging host per browser (Google Chrome, Google Chrome voor testen of Chromium). De systeemwijde native messaging hosts worden op een vaste locatie opgezocht, terwijl de native messaging hosts op gebruikersniveau worden opgezocht in de subdirectory NativeMessagingHosts/ van de gebruikersprofielmap .

macOS (systeembreed): Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome voor testen: /Library/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: /Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
macOS (gebruikersspecifiek, standaardpad ): Google Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome voor testen: ~/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 (systeembreed): Google Chrome: /etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json; Google Chrome voor testen: /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 (gebruikersspecifiek, standaardpad ): Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome voor testen: ~/.config/google-chrome-for-testing/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Native berichtenprotocol

Chrome start elke native berichtenhost in een apart proces en communiceert ermee via standaardinvoer ( stdin ) en standaarduitvoer ( stdout ). Hetzelfde formaat wordt gebruikt om berichten in beide richtingen te verzenden; elk bericht wordt geserialiseerd met JSON, UTF-8-gecodeerd en voorafgegaan door een 32-bits berichtlengte in native bytevolgorde. De maximale grootte van een enkel bericht van de native berichtenhost is 1 MB, voornamelijk om Chrome te beschermen tegen problemen met native applicaties. De maximale grootte van het bericht dat naar de native berichtenhost wordt verzonden, is 64 MiB.

Het eerste argument voor de native messaging host is de oorsprong van de beller, meestal chrome-extension://[ID of allowed extension] . Dit stelt native messaging hosts in staat de bron van het bericht te identificeren wanneer meerdere extensies zijn gespecificeerd in de sleutel allowed_origins in het manifest van de native messaging host .

Op Windows krijgt de native berichtenhost ook een opdrachtregelargument mee met een handle naar het aanroepende native Chrome-venster: --parent-window=<decimal handle value> . Hiermee kan de native berichtenhost native UI-vensters maken die correct gekoppeld zijn aan een oudervenster. Merk op dat deze waarde 0 zal zijn als de aanroepende context een service worker is.

Wanneer een berichtenpoort wordt aangemaakt met runtime.connectNative() `, start Chrome een native berichtenhostproces en houdt dit actief totdat de poort wordt vernietigd. Aan de andere kant, wanneer een bericht wordt verzonden met runtime.sendNativeMessage() , zonder een berichtenpoort aan te maken, start Chrome voor elk bericht een nieuw native berichtenhostproces. In dat geval wordt het eerste bericht dat door het hostproces wordt gegenereerd, behandeld als een antwoord op het oorspronkelijke verzoek, en Chrome geeft dit door aan de callbackfunctie die is opgegeven bij het aanroepen runtime.sendNativeMessage() . Alle andere berichten die in dat geval door het native berichtenhostproces worden gegenereerd, worden genegeerd.

Verbinding maken met een native applicatie

Het verzenden en ontvangen van berichten van en naar een native applicatie is vergelijkbaar met berichtenuitwisseling tussen extensies. Het belangrijkste verschil is dat runtime.connectNative() wordt gebruikt in plaats van runtime.connect() , en runtime.sendNativeMessage() in plaats van runtime.sendMessage() .

Om deze methoden te kunnen gebruiken, moet de machtiging "nativeMessaging" in het manifestbestand van uw extensie worden gedeclareerd .

Deze methoden zijn niet beschikbaar binnen content scripts, alleen binnen de pagina's van uw extensie en de service worker. Om vanuit een content script met de native applicatie te communiceren, stuurt u het bericht naar uw service worker, die het vervolgens doorstuurt naar de native applicatie.

Het volgende voorbeeld maakt een runtime.Port -object aan dat is verbonden met de native berichtenhost com.my_company.my_application , begint te luisteren naar berichten van die poort en verzendt één uitgaand bericht:

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

Gebruik runtime.sendNativeMessage om een bericht naar de native applicatie te sturen zonder een poort aan te maken, bijvoorbeeld:

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

Foutopsporing van native berichten

Wanneer er problemen optreden met native berichtenverwerking, wordt diagnostische informatie naar het foutenlogboek van Chrome geschreven.

Linux en 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

Start Chrome met logboekregistratie ingeschakeld :

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

Gebruik de parameter --user-data-dir="%TEMP%\nm-debug" om een aparte instantie te starten zonder verbinding te maken met een bestaand Chrome-proces.

Om de uitvoer te bekijken, kunt u het bestand chrome_debug.log streamen met PowerShell:

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

Je kunt ook chrome_debug.log openen in een teksteditor en zoeken naar launch_context.cc of native_message_process_host.cc .

Details over het loggen van belangrijke gegevens

Fouten bij het opzoeken en parseren van het manifest in launch_context.cc worden als waarschuwingen geregistreerd. Gebruik --log-level=1 in plaats van 2 (FOUT), waarmee deze opstartdiagnostiek wordt onderdrukt.
Zoek naar launch_context om manifest- en binaire opstartfouten te vinden, en native_messag om fouten in de payloadgrootte en pijpcommunicatie te vinden.

Veelvoorkomende fouten

Hieronder vindt u enkele veelvoorkomende fouten en tips om ze op te lossen:

Het is niet gelukt om de native berichtenhost te starten.

Controleer of u voldoende machtigingen hebt om het native berichtenhostbestand uit te voeren.

Er is een ongeldige hostnaam voor native berichtenverkeer opgegeven.

Controleer of de naam ongeldige tekens bevat. Alleen kleine letters, cijfers, underscores en punten zijn toegestaan. Een naam mag niet met een punt beginnen of eindigen, en een punt mag niet door een ander punt worden gevolgd.

De native host is afgesloten.

De verbinding met de native berichtenserver werd verbroken voordat Chrome het bericht kon lezen. Dit wordt hoogstwaarschijnlijk veroorzaakt door uw native berichtenserver.

De opgegeven native berichtenhost is niet gevonden.

Controleer het volgende:

Is de naam correct gespeld in de extensie en in het manifestbestand?
Bestaat de registersleutel op Windows onder HKEY_CURRENT_USER of HKEY_LOCAL_MACHINE , en verwijst de standaardwaarde ervan naar het volledige manifestpad? Chrome raadpleegt eerst de 32-bits registerweergave en vervolgens de 64-bits weergave. Gebruik regedit om de sleutel te controleren. Zie de locatie van de native berichtenhost .
Bevindt het manifestbestand zich op macOS en Linux in de verwachte map en is het genoemd naar de host (bijvoorbeeld com.my_company.my_application.json )? Zie native messaging host location .
Heeft het manifestbestand het juiste formaat? Is de JSON in het bijzonder geldig en goed opgemaakt en komen de waarden overeen met de definitie van een native messaging host-manifest ?
Bestaat het bestand dat in path is opgegeven? Op Windows mogen paden relatief zijn, maar op macOS en Linux moeten paden absoluut zijn.

Toegang tot de opgegeven native berichtenhost is verboden.

Staat de oorsprong van de extensie vermeld in allowed_origins ?

Fout bij de communicatie met de native berichtenhost.

Dit duidt op een onjuiste implementatie van het communicatieprotocol in de native berichtenhost.

Zorg ervoor dat alle uitvoer naar stdout voldoet aan het native berichtenprotocol . Als u gegevens wilt afdrukken voor debugdoeleinden, schrijf dan naar stderr .
Zorg ervoor dat de 32-bits berichtlengte de native integer-indeling van het platform heeft (little-endian / big-endian).
De lengte van het bericht mag niet groter zijn dan 1024*1024.
De berichtgrootte moet gelijk zijn aan het aantal bytes in het bericht. Dit kan verschillen van de "lengte" van een tekenreeks, omdat tekens door meerdere bytes kunnen worden weergegeven.
Alleen voor Windows: Zorg ervoor dat de I/O-modus van het programma is ingesteld op O_BINARY . Standaard is de I/O-modus O_TEXT , wat de berichtindeling verstoort doordat regeleinden ( \n = 0A ) worden vervangen door regeleinden in Windows-stijl ( \r\n = 0D 0A ). De I/O-modus kan worden ingesteld met __setmode .