Messaggi nativi

Le estensioni possono scambiare messaggi con applicazioni native utilizzando un'API simile alle altre API per la trasmissione di 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 l'host utilizzando flussi di input standard e stream di output standard.

Host di messaggistica nativo

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

Di seguito è riportato un esempio di 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 nativo deve essere un file JSON valido e contenere i seguenti campi:

name

Nome dell'host di messaggistica nativo. I client trasmettono 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 programma binario dell'host di messaggistica nativo. Su Linux e macOS, il percorso deve essere assoluto. Su Windows, può essere relativa alla directory che contiene il file manifest. Il processo host viene avviato con la directory corrente impostata sulla directory che contiene il programma binario dell'host. Ad esempio, se questo parametro è impostato su C:\Application\nm_host.exe, verrà avviato con la directory attuale "C:\Application".

type

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

allowed_origins

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

Posizione host di messaggistica nativa

La posizione del file manifest dipende dalla piattaforma.

Su Windows, il file manifest può essere posizionato ovunque nel 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 tale 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 host di messaggistica nativi, viene eseguita prima una query sul Registro di sistema a 32 bit, poi sul Registro di sistema a 64 bit.

Su macOS e Linux, la posizione del file manifest dell'host di messaggistica nativo varia a seconda del browser (Google Chrome o Chromium). Gli host di messaggistica nativi a livello di sistema vengono individuati in una posizione fissa, mentre gli host di messaggistica nativi a livello di utente vengono individuati 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 (specifico per l'utente, percorso predefinito)

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 dell'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 nativo

Chrome avvia ogni host di messaggistica nativo in un processo separato e comunica con l'host standard 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 con codifica UTF-8 ed è preceduto da una lunghezza del messaggio a 32 bit in ordine di byte nativi. La dimensione massima di un singolo messaggio proveniente dall'host di messaggistica nativo è 1 MB, principalmente per proteggere Chrome dal comportamento anomalo delle applicazioni native. La dimensione massima del messaggio inviato all'host di messaggistica nativo è 4 GB.

Il primo argomento dell'host di messaggistica nativo è l'origine del chiamante, di solito chrome-extension://[ID of allowed extension]. In questo modo gli host di messaggi nativi possono identificare l'origine del messaggio quando sono specificate più estensioni nella chiave allowed_origins nel manifest dell'host di messaggistica nativo.

Su Windows, all'host di messaggistica nativo viene passato anche un argomento della riga di comando con un handle alla finestra nativa di Chrome della chiamata: --parent-window=<decimal handle value>. Ciò consente all'host di messaggistica nativa di creare finestre dell'interfaccia utente native che vengono correttamente associate come genitore. 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 nativo dell'host di messaggistica e lo mantiene in esecuzione fino a quando la porta non viene eliminata. Quando invece un messaggio viene inviato utilizzando runtime.sendNativeMessage(), senza creare una porta per i messaggi, Chrome avvia un nuovo processo nativo dell'host di messaggistica per ogni messaggio. In questo caso, il primo messaggio generato dal processo host viene gestito come una risposta alla richiesta originale e Chrome lo passa al callback di risposta specificato quando viene chiamato runtime.sendNativeMessage(). In questo caso, tutti gli altri messaggi generati dall'host di messaggistica nativo vengono ignorati.

Connessione a un'applicazione nativa

L'invio e la ricezione di messaggi da e verso un'applicazione nativa è molto simile alla messaggistica su più estensioni. La differenza principale è che viene utilizzato runtime.connectNative() invece di runtime.connect(), mentre runtime.sendNativeMessage() viene utilizzato al posto di runtime.sendMessage().

Per utilizzare questi metodi, devi dichiarare l'autorizzazione"nativeMessaging" nel file manifest delle estensioni.

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

L'esempio seguente crea un oggetto runtime.Port connesso all'host di messaggistica nativo com.my_company.my_application, inizia ad ascoltare i messaggi provenienti 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);
  }
);

Esegui il debug della messaggistica nativa

Quando si verificano alcuni errori di messaggistica nativa, l'output viene scritto nel log degli errori di Chrome. Sono inclusi i casi in cui l'host di messaggistica nativo non si avvia, scrive su stderr o viola il protocollo di comunicazione. Su Linux e macOS, questo log è accessibile avviando Chrome dalla riga di comando e osservandone l'output nel terminale. Su Windows, utilizza --enable-logging come spiegato in Come abilitare il logging.

Di seguito sono riportati alcuni errori comuni e suggerimenti per risolverli:

Impossibile avviare l'host di messaggi nativi.

Verifica di disporre di autorizzazioni sufficienti per eseguire il file dell'host di messaggistica nativo.

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 barra verticale che rimanda all'host di messaggistica nativa è stata interrotta prima che il messaggio venisse letto da Chrome. È molto probabile che venga avviata dall'host di messaggistica nativo.

Host di messaggi nativi specificato non trovato.

Controlla quanto segue:

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

Nome host dell'host di messaggistica nativo non è registrato. (solo Windows)

Impossibile trovare l'host di messaggistica nativo nel Registro di sistema di Windows. Verifica con regedit se la chiave è stata effettivamente creata e se corrisponde al formato richiesto come documentato nella località host di messaggistica nativa.

È vietato accedere all'host di messaggistica nativo specificato.

L'origine dell'estensione è elencata in allowed_origins?

Errore durante la comunicazione con l'host di messaggistica nativo.

Questo indica un'implementazione errata del protocollo di comunicazione nell'host di messaggistica nativo.

• Assicurati che tutto l'output in stdout rispetti il protocollo di messaggistica nativo. Se vuoi stampare alcuni dati a scopo di debug, scrivi in stderr.
• Assicurati che la lunghezza del messaggio a 32 bit sia nel formato intero nativo della piattaforma (little-endian/big-endian).
• La lunghezza del messaggio non deve essere superiore a 1024*1024.
• Le dimensioni del messaggio devono essere uguali al numero di byte nel messaggio. Può differire dalla "lunghezza" di una stringa, perché i caratteri possono essere rappresentati da più byte.
• Solo Windows: assicurati che la modalità I/O del programma sia impostata su O_BINARY. Per impostazione predefinita, la modalità I/O è O_TEXT, che danneggia il formato del messaggio poiché le interruzioni di riga (\n = 0A) vengono sostituite con terminazioni di riga in stile Windows (\r\n = 0D 0A). La modalità I/O può essere impostata utilizzando __setmode.