Ir para o conteúdo

Como instalar e configurar a extensão de navegador

Este guia cobre a instalação completa da extensão Anotae em Windows (foco do beta 0.9.0-beta2), com notas para macOS e Linux. O Chrome é o caminho recomendado; Edge e Firefox seguem o mesmo padrão com pequenas diferenças.

Resumo em 4 passos

  1. Builde a extensão (uma vez): cd extension && npm ci && npm run build
  2. Registre o NMH: anotae install-extension --browser chrome
  3. Carregue a pasta extension/dist/chrome/ no chrome://extensions/ em modo desenvolvedor
  4. Confirme que o ID exibido é hfebcjlpbgegopcdllhannfmfihbnhcm

Pré-requisitos

  • Anotae 0.9.0-beta2 instalado (Anotae.exe para Windows ou pip install -e . rodando do source)
  • Node.js 22+ (para buildar a extensão localmente; se você baixou o chrome.zip do Release, pula essa parte)
  • Chrome 110+ (ou Edge 110+, Firefox 109+)

Passo 1 — Builde a extensão

A extensão é distribuída como código TypeScript fonte; é preciso buildar para gerar extension/dist/chrome/ e extension/dist/firefox/.

cd extension
npm ci          # instala deps (~30s)
npm run build   # builda Chrome + Firefox (~3s)

A pasta extension/dist/chrome/ deve conter:

extension/dist/chrome/
├── manifest.json
├── background.js
├── content.js
├── popup.js
├── popup/popup.html
├── icons/icon-{16,48,128}.png
└── assets/popup.css

Atalho: se você não quiser instalar Node, baixe o ZIP pré-buildado do Release mais recente em https://github.com/anotae/anotae/releases. Descompacte e use a pasta chrome/ como extension/dist/chrome/.

Passo 2 — Registre o Native Messaging Host (NMH)

O NMH é o canal pelo qual a extensão conversa com o app desktop. Precisa ser registrado no sistema antes que o navegador permita a comunicação.

Opção A — Pelo app (assistente gráfico)

  1. Abra o Anotae
  2. Menu Ajuda → Instalar extensão de navegador...
  3. Clique em Registrar para Chrome (ou Edge/Firefox)
  4. O assistente mostra o caminho do manifesto registrado e os próximos passos

Opção B — Pela linha de comando

No Windows (PowerShell ou Prompt de Comando):

anotae install-extension --browser chrome
# ou: --browser edge
# ou: --browser firefox

Saída esperada:

Instalando NMH para chrome...
  Executável: C:\...\Anotae.exe
  Diretório:  %LOCALAPPDATA%\Anotae\NativeMessagingHosts

[OK] Manifesto NMH instalado em:
     C:\Users\<você>\AppData\Local\Anotae\NativeMessagingHosts\ae.anot.anotae.json

Próximos passos para carregar a extensão Anotae:
  1. Abra chrome://extensions/
  2. Ative 'Modo desenvolvedor' (canto superior direito)
  3. Clique em 'Carregar sem compactação'
  4. Selecione a pasta extension/dist/chrome/ deste repositório
  5. Confirme que o ID é: hfebcjlpbgegopcdllhannfmfihbnhcm

No Windows, o registrador também grava uma chave em HKCU\Software\Google\Chrome\NativeMessagingHosts\ae.anot.anotae (ou Edge/Firefox correspondente) — é assim que o navegador encontra o manifesto.

Passo 3 — Carregue a extensão no navegador

Chrome / Edge / Chromium

  1. Acesse chrome://extensions/ (ou edge://extensions/)
  2. Habilite o Modo desenvolvedor (toggle superior direito)
  3. Clique em Carregar sem compactação
  4. Selecione a pasta extension/dist/chrome/
  5. A extensão Anotae aparece na lista. Confirme:
  6. ID: hfebcjlpbgegopcdllhannfmfihbnhcm (determinístico — bate com o NMH)
  7. Versão: 0.9.0 (com sufixo 0.9.0-beta2 em "Detalhes")
  8. Fixe o ícone da Anotae na barra (clique no ícone de quebra-cabeças → alfinete ao lado de Anotae)

Firefox

  1. Acesse about:debugging#/runtime/this-firefox
  2. Clique em Carregar extensão temporária...
  3. Selecione o arquivo extension/dist/firefox/manifest.json

Atenção Firefox: extensões temporárias somem ao reiniciar o navegador. Para uso permanente, será necessário publicar no AMO (Mozilla Add-ons) ou usar Firefox Developer Edition / Nightly com xpinstall.signatures.required = false.

Passo 4 — Verifique a conexão

  1. No Anotae, abra ou crie um vault
  2. Crie um atendimento de teste com S/O/A/P preenchido
  3. Abra https://sei.df.gov.br no Chrome
  4. Clique no ícone Anotae na barra do navegador → o popup deve listar o atendimento

Se aparecer "Falha ao conectar com o app" ou "Native messaging host not found", veja o troubleshooting abaixo.

Troubleshooting

"Native messaging host 'ae.anot.anotae' not found"

  • Causa: NMH não registrado para o navegador correto.
  • Solução: rode anotae install-extension --browser chrome (ajuste para o navegador em uso).

"Specified native messaging host not found" mesmo após registrar

  • Causa Windows: chave de registro não foi criada por falta de permissão.
  • Solução: abra PowerShell como Administrador e rode novamente. O NMH usa HKCU (current user), então normalmente não precisa de admin, mas alguns AVs bloqueiam.

Extensão carrega com ID diferente de hfebcjlpbgegopcdllhannfmfihbnhcm

  • Causa: o manifest.json em dist/chrome/ está sem o campo key.
  • Solução: rebuilde — cd extension && npm run build — o plugin do Vite copia o manifest.json correto (com key) do diretório fonte.
  • Verificação: python scripts/extension-keypair.py mostra o ID esperado.

"This extension may have been corrupted"

  • Causa: algum arquivo do dist/ ficou faltando após edição manual.
  • Solução: rm -rf extension/dist && cd extension && npm run build

Build do npm run build falha

  • Causa comum: Node.js < 22.
  • Solução: atualize Node. Verifique com node --version.

Anotae.exe foi movido depois de registrar o NMH

  • Causa: o manifesto NMH guarda caminho absoluto do executável.
  • Solução: rode anotae install-extension --browser chrome novamente; o caminho será reescrito.

macOS

Os passos 1, 3 e 4 são idênticos. Para o passo 2:

anotae install-extension --browser chrome

O manifesto vai para ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/ae.anot.anotae.json. Sem registro de sistema (não tem winreg).

Linux

Idem macOS, com manifesto em ~/.config/google-chrome/NativeMessagingHosts/.

Entendendo o canal de comunicação

Quando o popup da extensão chama "injetar atendimento":

  1. Background script da extensão envia mensagem via chrome.runtime.connectNative('ae.anot.anotae')
  2. Chrome consulta a chave registrada e encontra o caminho do manifesto JSON
  3. Manifesto JSON aponta para o executável do Anotae + lista os IDs de extensão permitidos (allowed_origins)
  4. Chrome confere que o ID da extensão (que clicou) bate com a lista
  5. Chrome inicia o processo Anotae em modo NMH (stdin/stdout = canal binário)
  6. Anotae responde com o atendimento serializado em JSON
  7. Content script injeta no formulário do site-alvo (e-SUS APS PEC, SISREG III, SEI/DF)

Tudo é local. Nenhum byte sai da máquina.

Para detalhes técnicos, ver docs/explanation/extensao-key-id.md.

Mais