Messaggi nativi

Le estensioni possono scambiare messaggi con le applicazioni native utilizzando un'API simile alle altre API di trasmissione dei messaggi. Le applicazioni native che supportano questa funzionalità devono registrare un host di messaggistica nativo in grado di comunicare con l'estensione. Chrome avvia l'host in un processo separato e comunica con esso utilizzando i flussi di input e output standard.

Host di messaggistica nativa

Per registrare un host di messaggistica nativa, l'applicazione deve salvare un file che definisce la configurazione dell'host di messaggistica nativa.

Di seguito è riportato un esempio del file:

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

Il file manifest dell'host di messaggistica nativa deve essere un file JSON valido e contenere i seguenti campi:

name

Nome dell'host di messaggistica nativa. I client passano questa stringa a runtime.connectNative() o runtime.sendNativeMessage(). Questo nome può contenere solo caratteri alfanumerici minuscoli, trattini bassi e punti. Il nome non può iniziare o terminare con un punto e un punto non può essere seguito da un altro punto.

description

Breve descrizione dell'applicazione.

path

Percorso del file binario dell'host di messaggistica nativa. Su Linux e macOS il percorso deve essere assoluto. Su Windows può essere relativo alla directory contenente il file manifest. Il processo host viene avviato con la directory corrente impostata sulla directory che contiene il file binario host. Ad esempio, se questo parametro è impostato su C:\Application\nm_host.exe, verrà avviato con la directory corrente `C:\Application`.

type

Tipo di interfaccia utilizzata per comunicare con l'host di messaggistica nativa. Questo parametro ha un solo valore possibile: stdio. Indica che Chrome deve utilizzare stdin e stdout per comunicare con l'host.

allowed_origins

Elenco delle estensioni che devono avere accesso all'host di messaggistica nativa. I valori di allowed-origins non possono contenere caratteri jolly.

Posizione dell'host di messaggistica nativa

La posizione del file manifest dipende dalla piattaforma.

Su Windows, il file manifest può trovarsi in qualsiasi punto del file system. Il programma di installazione dell'applicazione deve creare una chiave del Registro di sistema, HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application o HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, e impostare il valore predefinito di questa chiave sul percorso completo del file manifest. Ad esempio, utilizzando il seguente comando:

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

o utilizzando il seguente file .reg:

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

Quando Chrome cerca gli host di messaggistica nativa, viene eseguita prima una query sul registro a 32 bit, poi su quello a 64 bit.

Su macOS e Linux, la posizione del file manifest dell'host di messaggistica nativa varia a seconda del browser (Google Chrome o Chromium). Gli host di messaggistica nativa a livello di sistema vengono cercati in una posizione fissa, mentre gli host di messaggistica nativa a livello di utente vengono cercati nella sottodirectory NativeMessagingHosts/ della directory del profilo utente.

macOS (a livello di sistema)

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 (percorso predefinito specifico per l'utente)

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 (a livello di sistema)

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 (specifico per l'utente, percorso predefinito)

Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json

Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Protocollo di messaggistica nativa

Chrome avvia ogni host di messaggistica nativa in un processo separato e comunica con esso utilizzando l'input standard (stdin) e l'output standard (stdout). Lo stesso formato viene utilizzato per inviare messaggi in entrambe le direzioni; ogni messaggio viene serializzato utilizzando JSON, codificato in UTF-8 ed è preceduto dalla lunghezza del messaggio a 32 bit nell'ordine dei byte nativo. La dimensione massima di un singolo messaggio dall'host di messaggistica nativa è 1 MB, principalmente per proteggere Chrome da applicazioni native che non funzionano correttamente. La dimensione massima del messaggio inviato all'host di messaggistica nativa è 64 MiB.

Il primo argomento dell'host di messaggistica nativa è l'origine del chiamante, di solito chrome-extension://[ID of allowed extension]. Ciò consente agli host di messaggistica nativi di identificare l'origine del messaggio quando vengono specificate più estensioni nella chiave allowed_origins nel manifest dell'host di messaggistica nativa.

Su Windows, all'host di messaggistica nativa viene passato anche un argomento della riga di comando con un handle alla finestra nativa di Chrome chiamante: --parent-window=<decimal handle value>. In questo modo, l'host di messaggistica nativa può creare finestre dell'interfaccia utente nativa con la relazione padre-figlio corretta. Tieni presente che questo valore sarà 0 se il contesto di chiamata è un service worker.

Quando viene creata una porta di messaggistica utilizzando runtime.connectNative(), Chrome avvia il processo host di messaggistica nativa e lo mantiene in esecuzione finché la porta non viene eliminata. D'altra parte, quando un messaggio viene inviato utilizzando runtime.sendNativeMessage(), senza creare una porta di messaggistica, Chrome avvia un nuovo processo host di messaggistica nativa per ogni messaggio. In questo caso, il primo messaggio generato dal processo host viene gestito come risposta alla richiesta originale e Chrome lo passa al callback di risposta specificato quando viene chiamato runtime.sendNativeMessage(). Tutti gli altri messaggi generati dall'host di messaggistica nativa in questo caso vengono ignorati.

Connessione a un'applicazione nativa

L'invio e la ricezione di messaggi da e verso un'applicazione nativa sono molto simili alla messaggistica tra estensioni. La differenza principale è che runtime.connectNative() viene utilizzato al posto di runtime.connect() e runtime.sendNativeMessage() viene utilizzato al posto di runtime.sendMessage().

Per utilizzare questi metodi, l'autorizzazione"nativeMessaging" deve essere dichiarata nel file manifest delle tue estensioni.

Questi metodi non sono disponibili all'interno degli script dei contenuti, ma solo nelle pagine e nel service worker dell'estensione. Se vuoi comunicare da uno script dei contenuti all'applicazione nativa, invia il messaggio al service worker per passarlo all'applicazione nativa.

Il seguente esempio crea un oggetto runtime.Port connesso all'host di messaggistica nativa com.my_company.my_application, inizia ad ascoltare i messaggi da quella porta e invia un messaggio in uscita:

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

Utilizza runtime.sendNativeMessage per inviare un messaggio all'applicazione nativa senza creare una porta, ad esempio:

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

Eseguire il debug della messaggistica nativa

Quando si verificano determinati errori di messaggistica nativa, l'output viene scritto nel log degli errori di Chrome. Ciò include quando l'host di messaggistica nativa non viene avviato, scrive in stderr o viola il protocollo di comunicazione. Su Linux e macOS, è possibile accedere a questo log avviando Chrome dalla riga di comando e osservando il suo output nel terminale. Su Windows, utilizza --enable-logging come spiegato in Come abilitare la registrazione.

Ecco alcuni errori comuni e suggerimenti per risolverli:

Impossibile avviare l'host di messaggistica nativa.

Verifica di disporre delle autorizzazioni sufficienti per eseguire il file host di Messaggistica nativa.

Nome host di messaggistica nativa specificato non valido.

Controlla se il nome contiene caratteri non validi. Sono consentiti solo caratteri alfanumerici minuscoli, trattini bassi e punti. Un nome non può iniziare o terminare con un punto e un punto non può essere seguito da un altro punto.

L'host nativo è uscito.

La pipe all'host di messaggistica nativa è stata interrotta prima che il messaggio venisse letto da Chrome. Molto probabilmente è stato avviato dall'host di messaggistica nativa.

L'host di messaggistica nativa specificato non è stato trovato.

Controlla quanto segue:

• Il nome è scritto correttamente nell'estensione e nel file manifest?
• Il file manifest si trova nella directory corretta e ha il nome giusto? Per i formati previsti, consulta la sezione Posizione dell'host di messaggistica nativa.
• Il file manifest è nel formato corretto? In particolare, il JSON è valido e ben formato e i valori corrispondono alla definizione di un manifest del componente di messaggistica nativa?
• Il file specificato in path esiste? Su Windows, i percorsi possono essere relativi, ma su macOS e Linux, devono essere assoluti.

Il nome host dell'host di messaggistica nativa non è registrato. (solo Windows)