As extensões podem trocar mensagens com aplicativos nativos usando uma API semelhante às outras APIs de transmissão de mensagens. Os aplicativos nativos que oferecem suporte a esse recurso precisam registrar um host de mensagens nativo que possa se comunicar com a extensão. O Chrome inicia o host em um processo separado e se comunica com ele usando streams de entrada e saída padrão.
Host de mensagens nativas
Para registrar um host de mensagens nativo, o aplicativo precisa salvar um arquivo que define a configuração do host de mensagens nativo.
Confira um exemplo do arquivo:
{ "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/"] } O arquivo de manifesto do host de mensagens nativas precisa ser um JSON válido e conter os seguintes campos:
name- Nome do host de mensagens nativas. Os clientes transmitem essa string para
runtime.connectNative()ouruntime.sendNativeMessage(). O nome só pode conter caracteres alfanuméricos minúsculos, sublinhados e pontos. O nome não pode começar ou terminar com um ponto, e um ponto não pode ser seguido por outro ponto. description- Breve descrição do aplicativo.
path- Caminho para o binário do host de mensagens nativas. No Linux e no macOS, o caminho precisa ser absoluto. No Windows, ele pode ser relativo ao diretório que contém o arquivo de manifesto. O processo do host é iniciado com o diretório atual definido como o diretório que contém o binário do host. Por exemplo, se esse parâmetro for definido como
C:\Application\nm_host.exe, ele será iniciado com o diretório atual "C:\Application". type- Tipo da interface usada para se comunicar com o host de mensagens nativo. Esse parâmetro tem um valor possível:
stdio. Ele indica que o Chrome precisa usarstdinestdoutpara se comunicar com o host. allowed_origins- Lista de extensões que precisam ter acesso ao host de mensagens nativas. Os valores
allowed-originsnão podem conter caracteres curinga.
Local do host de mensagens nativas
O local do arquivo de manifesto depende da plataforma.
No Windows, o arquivo de manifesto pode estar localizado em qualquer lugar do sistema de arquivos. O instalador do aplicativo precisa criar uma chave de registro, HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application ou HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, e definir o valor padrão dessa chave para o caminho completo do arquivo de manifesto. Por exemplo, usando o seguinte 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 ou usando o seguinte arquivo .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 o Chrome procura hosts de mensagens nativas, o registro de 32 bits é consultado primeiro, depois o de 64 bits.
No macOS e no Linux, o local do arquivo de manifesto do host de mensagens nativas varia de acordo com o navegador (Google Chrome ou Chromium). Os hosts de mensagens nativas em todo o sistema são procurados em um local fixo, enquanto os hosts de mensagens nativas no nível do usuário são procurados no subdiretório NativeMessagingHosts/ do diretório de perfil do usuário.
- macOS (em todo o 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 (caminho padrão específico do usuário)
- 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 (em todo o 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 (caminho padrão específico do usuário)
- Google Chrome:
~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json - Chromium:
~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json
Protocolo de mensagens nativo
O Chrome inicia cada host de mensagens nativo em um processo separado e se comunica com ele usando entrada padrão (stdin) e saída padrão (stdout). O mesmo formato é usado para enviar mensagens nas duas direções. Cada mensagem é serializada usando JSON, codificada em UTF-8 e é precedida por uma comprimento de mensagem de 32 bits na ordem de bytes nativa. O tamanho máximo de uma única mensagem do host de mensagens nativas é de 1 MB, principalmente para proteger o Chrome de aplicativos nativos com comportamento incorreto. O tamanho máximo da mensagem enviada para o host de mensagens nativo é de 64 MB.
O primeiro argumento para o host de mensagens nativo é a origem do autor da chamada, geralmente chrome-extension://[ID of allowed extension]. Isso permite que os hosts de mensagens nativas identifiquem a origem da mensagem quando várias extensões são especificadas na chave allowed_origins no manifesto do host de mensagens nativas.
No Windows, o host de mensagens nativas também recebe um argumento de linha de comando com um identificador para a janela nativa do Chrome que está chamando: --parent-window=<decimal handle value>. Isso permite que o host de mensagens nativas crie janelas de interface nativas com o pai correto. Esse valor será 0 se o contexto de chamada for um service worker.
Quando uma porta de mensagens é criada usando runtime.connectNative(), o Chrome inicia o processo de host de mensagens nativas e o mantém em execução até que a porta seja destruída. Por outro lado, quando uma mensagem é enviada usando runtime.sendNativeMessage(), sem criar uma porta de mensagens, o Chrome inicia um novo processo de host de mensagens nativo para cada mensagem. Nesse caso, a primeira mensagem gerada pelo processo host é processada como uma resposta à solicitação original, e o Chrome a transmite ao callback de resposta especificado quando runtime.sendNativeMessage() é chamado. Todas as outras mensagens geradas pelo host de mensagens nativas nesse caso são ignoradas.
Como se conectar a um app nativo
Enviar e receber mensagens de e para um aplicativo nativo é muito semelhante às mensagens entre extensões. A principal diferença é que runtime.connectNative() é usado em vez de runtime.connect(), e runtime.sendNativeMessage() é usado em vez de runtime.sendMessage().
Para usar esses métodos, a permissão "nativeMessaging" precisa ser declarada no arquivo de manifesto das extensões.
Esses métodos não estão disponíveis em scripts de conteúdo, apenas nas páginas e no worker de serviço da sua extensão. Se você quer se comunicar de um script de conteúdo para o aplicativo nativo, envie a mensagem para o service worker para que ela seja transmitida ao aplicativo nativo.
O exemplo a seguir cria um objeto runtime.Port conectado ao host de mensagens nativas com.my_company.my_application, começa a detectar mensagens dessa porta e envia uma mensagem de saída:
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'}); Use runtime.sendNativeMessage para enviar uma mensagem ao aplicativo nativo sem criar uma porta, por exemplo:
chrome.runtime.sendNativeMessage( 'com.my_company.my_application', {text: 'Hello'}, function (response) { console.log('Received ' + response); } ); Depurar mensagens nativas
Quando ocorrem falhas de mensagens nativas, a saída é gravada no registro de erros do Chrome. Isso inclui quando o host de mensagens nativas não inicia, grava em stderr ou viola o protocolo de comunicação. No Linux e no macOS, esse registro pode ser acessado iniciando o Chrome na linha de comando e observando a saída no terminal. No Windows, use --enable-logging, conforme explicado em Como ativar o registro.
Confira alguns erros comuns e dicas para resolvê-los:
Não foi possível iniciar o host de mensagens nativas.
Verifique se você tem permissões suficientes para executar o arquivo de host de mensagens nativas.
Nome de host de mensagens nativas inválido especificado.
Verifique se o nome contém caracteres inválidos. Apenas caracteres alfanuméricos minúsculos, sublinhados e pontos são permitidos. Um nome não pode começar ou terminar com um ponto, e um ponto não pode ser seguido por outro ponto.
O host nativo foi encerrado.
O pipe para o host de mensagens nativas foi interrompido antes que a mensagem fosse lida pelo Chrome. Isso provavelmente é iniciado pelo host de mensagens nativas.
O host de mensagens nativas especificado não foi encontrado.
Verifique os seguintes itens:
- O nome está escrito corretamente na extensão e no arquivo de manifesto?
- O manifesto está no diretório certo e com o nome correto? Consulte o local do host de mensagens nativas para saber os formatos esperados.
- O arquivo de manifesto está no formato correto? Em particular, o JSON é válido e bem formado, e os valores correspondem à definição de um manifesto de host de mensagens nativas?
- O arquivo especificado em
pathexiste? No Windows, os caminhos podem ser relativos, mas no macOS e no Linux, eles precisam ser absolutos.
O host de mensagens nativas nome do host não está registrado. (somente no Windows)
O host de mensagens nativas não foi encontrado no registro do Windows. Verifique novamente usando regedit se a chave foi realmente criada e corresponde ao formato necessário, conforme documentado no local de hospedagem de mensagens nativo.
O acesso ao host de mensagens nativas especificado é proibido.
A origem da extensão está listada em allowed_origins?
Erro ao se comunicar com o host de mensagens nativo.
Isso indica uma implementação incorreta do protocolo de comunicação no host de mensagens nativas.
- Verifique se toda a saída em
stdoutsegue o protocolo de mensagens nativo. Se você quiser imprimir alguns dados para fins de depuração, escreva emstderr. - Verifique se o comprimento da mensagem de 32 bits está no formato de número inteiro nativo da plataforma (little-endian / big-endian).
- A mensagem não pode ter mais de 1.024*1.024.
- O tamanho da mensagem precisa ser igual ao número de bytes nela. Isso pode ser diferente do "comprimento" de uma string, porque os caracteres podem ser representados por vários bytes.
- Somente Windows:verifique se o modo de E/S do programa está definido como
O_BINARY. Por padrão, o modo de E/S éO_TEXT, o que corrompe o formato da mensagem, já que os quebras de linha (\n=0A) são substituídos por terminações de linha no estilo do Windows (\r\n=0D 0A). O modo de E/S pode ser definido usando__setmode.