Messaggi nativi

Le estensioni possono scambiare messaggi con applicazioni native utilizzando un'API simile alle altre API di passaggio 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 stream 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.

Un esempio di file è il seguente:

{
  "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 JSON valido e contenere i seguenti campi:

name

Nome dell'host di messaggistica nativa. I clienti 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

Descrizione breve 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 contenente il file binario dell'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 nativo. Questo parametro ha un possibile valore: stdio. Indica che Chrome deve utilizzare stdin e stdout per comunicare con l'host.

allowed_origins

Elenco di estensioni che devono avere accesso all'host di messaggistica nativo. I valori 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 posizione 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 della 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

oppure 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 nativa, viene eseguita una query prima nel registry a 32 bit e poi nel registry 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 nativa a livello di sistema vengono cercati in una posizione fissa, mentre quelli 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 dell'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 (percorso predefinito specifico dell'utente)

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 nativa in un processo separato e comunica con esso utilizzando input standard (stdin) e output standard (stdout). Lo stesso formato viene utilizzato per inviare messaggi in entrambe le direzioni. Ogni messaggio viene serializzato utilizzando JSON, codifica UTF-8 ed è preceduto dalla lunghezza del messaggio in bit 32 nell'ordine di byte nativo. La dimensione massima di un singolo messaggio dall'host di messaggistica nativa è 1 MB, principalmente per proteggere Chrome da applicazioni native con comportamenti errati. La dimensione massima del messaggio inviato all'host di messaggistica nativa è 4 GB.

Il primo argomento per l'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 del 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 per la finestra nativa di Chrome che chiama: --parent-window=<decimal handle value>. In questo modo, l'host di messaggistica nativa può creare finestre dell'interfaccia utente nativa con un'associazione 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 dell'host di messaggistica nativa e lo mantiene in esecuzione fino a quando la porta non viene distrutta. Invece, quando un messaggio viene inviato utilizzando runtime.sendNativeMessage(), senza creare una porta di messaggistica, Chrome avvia una nuova procedura di hosting 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 trasmetterà 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 ai messaggi tra estensioni. La differenza principale è che viene utilizzato runtime.connectNative() anziché runtime.connect() e runtime.sendNativeMessage() anziché runtime.sendMessage().

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

Questi metodi non sono disponibili negli script di contenuti, ma solo all'interno delle pagine delle estensioni e del service worker. Se vuoi comunicare da uno script di contenuti all'applicazione nativa, invia il messaggio al tuo service worker per inoltrarlo all'applicazione nativa.

Nell'esempio seguente viene creato un oggetto runtime.Port connesso all'host di messaggistica nativo 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. Sono inclusi i casi in cui l'host di Messaggistica nativa non riesce ad avviarsi, 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 l'output nel terminale. Su Windows, utilizza --enable-logging come spiegato in Come abilitare il logging.

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.

Il canale all'host di Messaggistica nativa è stato interrotto prima che il messaggio venisse letto da Chrome. Molto probabilmente è stata avviata 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 con il nome corretto? Per i formati previsti, consulta la 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 host 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)