Mensagens nativas

Artigo
01/19/2024

Para se comunicar com um aplicativo nativo do Win32 instalado no dispositivo de um usuário, uma extensão usa uma API semelhante à outra mensagem que passa APIs. O host de aplicativo nativo envia e recebe mensagens com extensões usando entrada padrão e saída padrão.

Extensões que usam mensagens nativas são instaladas no Microsoft Edge semelhantes a qualquer outra extensão. No entanto, os aplicativos nativos não são instalados ou gerenciados pelo Microsoft Edge.

Para adquirir a extensão e o host de aplicativo nativo, há dois modelos de distribuição diferentes:

Empacote sua extensão e o host juntos. Quando um usuário instala o pacote, a extensão e o host são instalados.
Ou instale sua extensão usando o site de Complementos do Microsoft Edge e sua extensão solicita que os usuários instalem o host.

Para criar sua extensão para enviar e receber mensagens com hosts de aplicativos nativos, siga as etapas a seguir.

Etapa 1: Adicionar permissões ao manifesto de extensão

Adicione a nativeMessaging permissão ao arquivo manifest.json da extensão.

Este é o arquivo de manifesto de extensão, não o arquivo de manifesto do host de mensagens nativo, que é abordado em seções posteriores.

Veja a seguir um arquivo manifest.json de exemplo:

Manifesto V3
Manifesto V2

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 3,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

Etapa 2: Criar seu arquivo de manifesto do host de mensagens nativas

Os aplicativos nativos devem fornecer um arquivo de manifesto de host de mensagens nativo. Um arquivo de manifesto do host de mensagens nativo contém as seguintes informações:

O caminho para o runtime do host de mensagens nativo.
O método de comunicação com a extensão.
Uma lista de extensões permitidas às quais ele se comunica.

O navegador lê e valida o manifesto do host de mensagens nativo. O navegador não instala nem gerencia o arquivo de manifesto do host de mensagens nativo.

O arquivo de manifesto do host de mensagens nativas é distinto do arquivo Manifest V3 ou V2 que faz parte da extensão do Microsoft Edge.

Exemplo de um arquivo de manifesto de host de mensagens nativo:

{
    "name": "com.my_company.my_app",
    "description": "My App",
    "path": "C:\\Program Files\\My App\\chrome_native_messaging_host.exe",
    "type": "stdio",
    "allowed_origins": [
        "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
    ]
}

O arquivo de manifesto do host de mensagens nativas deve ser um arquivo JSON válido que contém as seguintes chaves:

Chave	Detalhes
`name`	Especifica o nome do host de mensagens nativo. Os clientes passam a cadeia de caracteres para `runtime.connectNative` ou `runtime.sendNativeMessage`. O valor deve conter apenas caracteres alfanuméricos minúsculas, sublinhados e pontos. O valor não deve iniciar ou terminar com um ponto (um período) e um ponto não deve ser seguido por outro ponto.
`description`	Descreve o aplicativo.
`path`	Especifica o caminho para o binário do host de mensagens nativo. Em dispositivos Windows, você pode usar caminhos relativos para o diretório que contém o arquivo de manifesto do host de mensagens nativo. No macOS e no Linux, o caminho deve ser absoluto. O processo de host começa com o diretório atual definido para o diretório que contém o binário host. Por exemplo (Windows), se o parâmetro for definido como `C:\App\nm_host.exe`, o binário será iniciado usando o diretório atual (`C:\App\`).
`type`	Especifica o tipo da interface usada para se comunicar com o host de mensagens nativo. O valor instrui o Microsoft Edge a usar `stdin` e `stdout` a se comunicar com o host. O único valor aceitável é `stdio`.
`allowed_origins`	Especifica a lista de extensões que têm acesso ao host de mensagens nativo. Para ativar seu aplicativo para identificar e se comunicar com uma extensão, no arquivo de manifesto do host de mensagens nativo, defina o seguinte valor: `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

Carregar lateralmente sua extensão para testar mensagens nativas com o host. Para carregar a extensão durante o desenvolvimento e recuperar microsoft_catalog_extension_id:

Vá para edge://extensions, e ative o botão Alternar modo desenvolvedor .
Selecione Carregar descompactado e selecione seu pacote de extensão para sideload.
Clique em OK.
Acesse a edge://extensions página e verifique se sua extensão está listada.
Copie a chave de microsoft_catalog_extension_id (ID) da listagem de extensão na página.

Quando estiver pronto para distribuir sua extensão aos usuários, publique sua extensão no site de Complementos do Microsoft Edge. A ID de extensão da extensão publicada pode ser diferente da ID usada durante o sideload da extensão. Se a ID for alterada, atualize allowed_origins no arquivo de manifesto do host de mensagens nativo com a ID da extensão publicada.

Etapa 3: Copiar o arquivo de manifesto do host de mensagens nativas para o sistema

A etapa final envolve copiar o arquivo de manifesto do host de mensagens nativo para o computador e garantir que esse arquivo de manifesto esteja configurado corretamente. Para garantir que o arquivo de manifesto do host de mensagens nativas seja colocado no local esperado, siga as etapas a seguir. O local varia de acordo com a plataforma.

No Linux e no macOS:

Certifique-se de fornecer permissões de leitura no arquivo de manifesto do host de mensagens nativo.
Verifique se você fornece permissões de execução no runtime do host.

O arquivo de manifesto do host de mensagens nativas pode estar localizado em qualquer lugar do sistema de arquivos. O instalador do aplicativo deve criar uma chave de registro e definir o valor padrão da chave para o caminho completo do arquivo de manifesto do host de mensagens nativo.

Os seguintes locais são exemplos de chaves do registro:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

Para adicionar uma chave de registro ao diretório com a chave de manifesto, faça um dos seguintes procedimentos:

Execute um comando no prompt de comando:

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

Ou crie um .reg arquivo e execute-o da seguinte maneira:
1. Copie o seguinte comando em um .reg arquivo:
```
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app]
@="C:\\path\\to\\nmh-manifest.json"
```
2. Execute o .reg arquivo. Se você executar o arquivo criado .reg como parte de um script em lote, execute-o usando um prompt de comando de administrador.

O Microsoft Edge consulta a HKEY_CURRENT_USER chave raiz, seguida por HKEY_LOCAL_MACHINE. Em ambas as chaves, o registro de 32 bits é pesquisado primeiro e, em seguida, o registro de 64 bits é pesquisado para identificar hosts de mensagens nativos. A chave do registro especifica o local do arquivo de manifesto do host de mensagens nativo.

Se as entradas de registro do Microsoft Edge não tiverem o local do arquivo de manifesto do host de mensagens nativo, os locais de registro do Chromium e do Chrome serão usados como opções de fallback.

Se o Microsoft Edge encontrar a chave do registro em qualquer um dos locais listados anteriormente, ele não consultará os locais listados no snippet de código a seguir.

A ordem de pesquisa para os locais do registro é:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\

Nó de registro WOW6432Node

O HKEY_CURRENT_USER\SOFTWARE\WOW6432Node nó do registro não é pesquisado em computadores de 64 bits, devido à maneira como o registro funciona neles. Para obter mais informações, consulte Chaves do Registro afetadas por instalações do Windows que incluem suporte do Windows no Windows (WOW) para várias arquiteturas de processador.

IDs de extensão necessárias para ambos os repositórios

Se você tiver extensões nos Suplementos do Microsoft Edge e na Chrome Web Store, deverá adicionar as IDs de extensão correspondentes às duas lojas no allowed_origins arquivo de manifesto do host de mensagens nativo. Isso é necessário porque somente o arquivo de manifesto do host de mensagens nativo que corresponde ao primeiro local de registro encontrado é lido.

Para armazenar o arquivo de manifesto do host de mensagens nativo:

Os hosts de mensagens nativas em todo o sistema, que estão disponíveis para todos os usuários, são armazenados em um local fixo. Por exemplo, o arquivo de manifesto do host de mensagens nativo deve ser armazenado no seguinte local:
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
Os hosts de mensagens nativas específicos do usuário, que estão disponíveis apenas para o usuário atual, estão localizados no NativeMessagingHosts subdiretório no diretório de dados do usuário. Por exemplo, o arquivo de manifesto do host de mensagens nativo deve ser armazenado no seguinte local:
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
O {Channel_Name} in Microsoft Edge {Channel_Name} deve ser um dos seguintes valores:
- Canary
- Dev
- Beta
Ao usar o canal Estável, {Channel_Name} não é necessário.

Para armazenar o arquivo de manifesto do host de mensagens nativo:

Os hosts de mensagens nativas em todo o sistema, que estão disponíveis para todos os usuários, são armazenados em um local fixo. O arquivo de manifesto do host de mensagens nativas deve ser armazenado no seguinte local:
```
/etc/opt/edge/native-messaging-hosts
```
Os hosts de mensagens nativas específicos do usuário, que estão disponíveis apenas para o usuário atual, estão localizados no NativeMessagingHosts subdiretório no diretório de dados do usuário. O arquivo de manifesto do host de mensagens nativas deve ser armazenado no seguinte local:
```
~/.config/microsoft-edge/NativeMessagingHosts
```

Protocolo de mensagens nativo

O Microsoft Edge 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 em ambas as direções; cada mensagem é serializada usando JSON, UTF-8 codificada e é precedida com comprimento de mensagem de 32 bits em ordem de byte nativo. O tamanho máximo de uma única mensagem do host de mensagens nativas é de 1 MB, principalmente para proteger o Microsoft Edge de se comportar mal com aplicativos nativos. O tamanho máximo da mensagem enviada ao host de mensagens nativo é de 4 GB.

O primeiro argumento para o host de mensagens nativo é a origem do chamador, geralmente chrome-extension://[ID of allowed extension]. Isso permite que os hosts de mensagens nativos identifiquem a origem da mensagem quando várias extensões são especificadas na allowed_origins chave no manifesto do host de mensagens nativas; consulte Etapa 2: Criar seu arquivo de manifesto do host de mensagens nativo, acima.

No Windows, o host de mensagens nativo também é passado um argumento de linha de comando com um identificador para a janela nativa do Microsoft Edge: --parent-window=<decimal handle value>. Isso permite que o host de mensagens nativas crie janelas nativas da interface do usuário que são corretamente pai. Observe que esse valor será 0 se o contexto de chamada for um trabalho de serviço.

Quando uma porta de mensagens é criada usando runtime.connectNativeo , o Microsoft Edge inicia um processo de host de mensagens nativo e a 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 Microsoft Edge inicia um novo processo de host de mensagens nativas para cada mensagem. Nesse caso, a primeira mensagem gerada pelo processo de host é tratada como uma resposta à solicitação original e o Microsoft Edge a passará para o retorno de chamada de resposta especificado quando runtime.sendNativeMessage for chamado. Todas as outras mensagens geradas pelo host de mensagens nativas nesse caso são ignoradas.

Conectar-se a um aplicativo nativo

Enviar e receber mensagens de e para um aplicativo nativo é muito semelhante às mensagens de extensão cruzada. A diferença main é usada runtime.connectNative em vez de runtime.connect, e runtime.sendNativeMessage é usada em vez de runtime.sendMessage.

Para usar esses métodos, a nativeMessaging permissão deve ser declarada no arquivo de manifesto de suas extensões; consulte Etapa 1: Adicionar permissões ao manifesto de extensão acima.

Esses métodos não estão disponíveis dentro de scripts de conteúdo, somente dentro das páginas da sua extensão e do trabalho de serviço. Se você quiser se comunicar de um script de conteúdo para o aplicativo nativo, envie a mensagem ao seu funcionário de serviço para passá-la para o aplicativo nativo.

O exemplo a seguir cria um runtime.Port objeto conectado ao host com.my_company.my_applicationde mensagens nativo , começa a ouvir 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 para o aplicativo nativo sem criar uma porta; por exemplo:

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

Depuração de mensagens nativas

Quando determinadas falhas de mensagens nativas ocorrem, a saída é gravada no log de erros do Microsoft Edge. Isso inclui quando o host de mensagens nativo falha ao iniciar, grava stderr ou viola o protocolo de comunicação. No Linux e no macOS, esse log pode ser facilmente acessado iniciando o Microsoft Edge na linha de comando e observando sua saída no terminal. No Windows, use --enable-logging conforme explicado em Como habilitar o registro em log.

Aqui estão alguns erros comuns e dicas para resolvê-los:

Falha ao iniciar o host de mensagens nativas.

Verifique se você tem permissões suficientes para executar o arquivo de host de mensagens nativo.

Nome do host de mensagens nativas inválido especificado.

Verifique se o nome contém caracteres inválidos. Somente caracteres alfanuméricos minúsculas, sublinhados e pontos (períodos) são permitidos. Um nome não pode iniciar ou terminar com um ponto e um ponto não pode ser seguido por outro ponto.

O host nativo saiu.

O pipe para o host de mensagens nativo foi quebrado antes da mensagem ser lida pelo Microsoft Edge. Isso provavelmente é iniciado a partir do host de mensagens nativo.

Host de mensagens nativas especificado não encontrado.

Verificar o seguinte:

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 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 nativo, por Etapa 2: Criar o arquivo de manifesto do host de mensagens nativo acima?
O arquivo especificado no path existe? No Windows, os caminhos podem ser relativos, mas no macOS e no Linux, os caminhos devem ser absolutos.

O nome do host de mensagens nativas não está registrado. (Somente windows)

O host de mensagens nativo não foi encontrado no registro do Windows. O marcar usando regedit se a chave foi realmente criada e corresponde ao formato necessário conforme documentado no local do host de mensagens nativas.

O acesso ao host de mensagens nativo 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 nativo.

Verifique se toda a saída no stdout adere ao protocolo de mensagens nativo. Se você quiser imprimir alguns dados para fins de depuração, escreva em stderr.
Verifique se o comprimento da mensagem de 32 bits está no formato inteiro nativo da plataforma (little-endian ou big-endian).
O comprimento da mensagem não deve exceder 1024*1024.
O tamanho da mensagem deve ser igual ao número de bytes na mensagem. Isso pode ser diferente do "comprimento" de uma cadeia de caracteres, pois 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, que corrompe o formato de mensagem como quebras de linha (0A = \n) são substituídos por finais de linha no estilo Windows ().\r\n = 0D 0A O modo de E/S pode ser definido usando __setmode.

Observação

Partes desta página são modificações baseadas no trabalho criado e compartilhado pelo Google e usadas de acordo com os termos descritos na Licença Internacional de Atribuição do Creative Commons 4.0. A página original é encontrada aqui.

Este trabalho é licenciado sob uma Licença Internacional de Atribuição do Creative Commons 4.0.

Partilhar via