Guia de implementação e configuração de TI

Este documento é para o administrador de TI que precisa instalar o HoverSpeak de forma forçada em dispositivos de instituições de ensino, salas de aula, laboratórios ou contas de estudantes gerenciadas.

Pré-requisitos de implementação

• Versões do navegador: Chrome 109+ ou Edge 109+ para a extensão atual. O HoverSpeak usa documentos offscreen do Manifest V3 pela API chrome.offscreen, que exige Chrome 109+ / MV3+. O recurso opcional de definições de palavras exige Chrome 148+ porque depende da capacidade local de IA mais recente do Chrome; o Microsoft Edge não oferece suporte a esse recurso no momento.
• Permissões exigidas pela extensão:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Permissões de host: <all_urls>
• Entrada de esquema gerenciado em manifest.json:

{
  "storage": {
    "managed_schema": "schema.json"
  }
}

Modelo de política gerenciada

• As políticas são definidas em schema.json e lidas por chrome.storage.managed.
• Os valores efetivos são resolvidos nesta ordem:
  1. Política gerenciada
  2. Preferência sincronizada do usuário
  3. Padrão integrado
• As chaves de política de atalhos são apenas orientativas. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac e PauseShortcutMac atualizam as dicas de atalho exibidas pelo HoverSpeak, mas não forçam atalhos de teclado no Chrome ou Edge.
• Detecção de configuração gerenciada: O HoverSpeak trata a configuração como gerenciada quando a extensão é instalada por um administrador ou quando pelo menos uma chave de política gerenciada está presente. As configurações só são bloqueadas quando a chave de política correspondente está definida.

Instalação forçada passo a passo

Google Admin Console (Chrome)

1. Acesse Console de administração → Dispositivos → Chrome → Apps e extensões → Usuários e navegadores.
2. Selecione a unidade organizacional (OU) de destino.
3. Clique em + e adicione a extensão por ID:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Defina a política de instalação como Instalação forçada.
5. Abra os detalhes da extensão e configure Política → Armazenamento gerenciado com o payload JSON da seção de políticas abaixo.
6. Aplique a política à OU e aguarde a propagação.

Validação:

• Em um dispositivo de destino, abra chrome://policy e clique em Recarregar políticas.
• Confirme se a extensão aparece em chrome://extensions.

Microsoft Intune (Edge)

1. No Microsoft Intune, acesse Dispositivos → Perfis de configuração e crie ou edite um perfil para Windows 10 e posterior.
2. Use o Catálogo de configurações e adicione esta configuração:
   • Microsoft Edge → Extensões → Configurar definições de gerenciamento de extensões.
3. Adicione uma entrada de instalação forçada para o Edge usando o ID da loja:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • URL de atualização: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Adicione o payload JSON de armazenamento gerenciado da seção de políticas ao bloco de configuração da extensão.
5. Atribua o perfil ao grupo de dispositivos de destino.

Validação:

• Em um dispositivo de destino, abra edge://policy e clique em Recarregar políticas.
• Confirme se a extensão aparece em edge://extensions.

Esquema de política gerenciada (chrome.storage.managed)

O esquema de política gerenciada fica em schema.json e é lido pelo service worker via chrome.storage.managed.

Referência de chaves de política

Todas as chaves pertencem ao namespace de políticas da extensão e correspondem a schema.json.

{
  "type": "object",
  "properties": {
    "EnableCloudVoices": {
      "type": "boolean",
      "description": "If false, cloud voices remain disabled by policy."
    },
    "OrganizationName": {
      "type": "string",
      "description": "Displays the educational institution, district, or program name in the extension settings interface."
    },
    "OrganizationUrl": {
      "type": "string",
      "description": "Link target for the organization name in the extension settings interface."
    },
    "FollowMouse": {
      "type": "boolean",
      "description": "If true, always highlight text under the mouse."
    },
    "AutoSwitchLanguage": {
      "type": "boolean",
      "description": "Automatically switch language to match the language of the page."
    },
    "ShowLanguageToast": {
      "type": "boolean",
      "description": "Display a message when language switches."
    },
    "WordByWordHighlightingEnabled": {
      "type": "boolean",
      "description": "If false, disables Word-by-Word highlighting for long selected text."
    },
    "ReadShortcutWindows": {
      "type": "string",
      "description": "Admin-defined shortcut hint for the Start reading command on Windows."
    },
    "StopShortcutWindows": {
      "type": "string",
      "description": "Admin-defined shortcut hint for the Stop reading command on Windows."
    },
    "PauseShortcutWindows": {
      "type": "string",
      "description": "Admin-defined shortcut hint for the Pause / Continue command on Windows."
    },
    "ReadShortcutMac": {
      "type": "string",
      "description": "Admin-defined shortcut hint for the Start reading command on macOS."
    },
    "StopShortcutMac": {
      "type": "string",
      "description": "Admin-defined shortcut hint for the Stop reading command on macOS."
    },
    "PauseShortcutMac": {
      "type": "string",
      "description": "Admin-defined shortcut hint for the Pause / Continue command on macOS."
    },
    "HideDonationAndRating": {
      "type": "boolean",
      "description": "If true, hides the donation and rating area."
    }
  }
}

Exemplo de payload de armazenamento gerenciado

Use este JSON na área de armazenamento gerenciado do Admin Console ou Intune:

{
  "EnableCloudVoices": false,
  "OrganizationName": "Westside Learning Center",
  "OrganizationUrl": "https://www.westside.edu",
  "FollowMouse": true,
  "AutoSwitchLanguage": true,
  "ShowLanguageToast": false,
  "WordByWordHighlightingEnabled": true,
  "HideDonationAndRating": true,
  "ReadShortcutWindows": "Alt+Z",
  "StopShortcutWindows": "Alt+X",
  "PauseShortcutWindows": "Alt+C",
  "ReadShortcutMac": "Option+Z",
  "StopShortcutMac": "Option+X",
  "PauseShortcutMac": "Option+C"
}

Exemplos comuns de políticas

• Use EnableCloudVoices para permitir ou bloquear vozes em nuvem. Defina como false para forçar apenas vozes locais.
• Para exibir a marca nas configurações da extensão, defina OrganizationName e, opcionalmente, OrganizationUrl para mostrar HoverSpeak provided by <name>.
• Defina WordByWordHighlightingEnabled para bloquear Word-by-Word ligado ou desligado. O limite continua sendo uma preferência do usuário e o padrão é mais de 40 palavras.
• Use ReadShortcut*, StopShortcut* e PauseShortcut* apenas como dicas de atalho exibidas. As atribuições do navegador continuam controladas pelo Chrome ou Edge.

Notas de implementação específicas da plataforma

Caminho do Registro do Windows (Chrome)

Para implementações do Chrome fora do Google Admin Console, o Windows lê a política da extensão no caminho do Registro abaixo:

HKEY_CURRENT_USER\Software\Policies\Google\Chrome\3rdparty\extensions\<EXTENSION_ID>\policy

• Substitua <EXTENSION_ID> pelo ID da extensão HoverSpeak em chrome://extensions.
• Use DWORD (32-bit) para chaves booleanas.
• Use REG_SZ para chaves de texto.
• Depois de fazer alterações, reinicie o Chrome e recarregue chrome://policy.

Perfis gerenciados do macOS

No macOS, as políticas do HoverSpeak são entregues por perfis de configuração gerenciada do Chrome. Use o identificador de pacote correto do Chrome e o namespace de política da extensão; depois recarregue chrome://policy para confirmar que o perfil está ativo.

Lista de validação

• Recarregue chrome://policy ou edge://policy e confirme que a entrada de política não mostra erros de análise ou tipo.
• Confirme que a extensão está presente e atualizada em chrome://extensions ou edge://extensions.
• Abra as configurações do HoverSpeak e confirme que os controles gerenciados estão bloqueados onde a política foi definida.
• Confirme que dicas ou rótulos gerenciados aparecem para controles bloqueados.
• Verifique se WordByWordHighlightingEnabled=true bloqueia Word-by-Word ligado enquanto o limite independente de palavras continua editável.
• Verifique se o texto selecionado deve exceder o limite configurado de Word-by-Word, cujo padrão é mais de 40 palavras.
• Verifique se HideDonationAndRating=true remove a área de doação e avaliação.
• Verifique se EnableCloudVoices=false mantém as vozes em nuvem desativadas.
• Verifique se o comportamento da página reflete as configurações gerenciadas ao carregar a página e após a atualização de políticas.
• Verifique se a marca da organização aparece quando OrganizationName está configurado.
• Em implantações gerenciadas, confirme que a integração gerenciada é aplicada mesmo quando a extensão foi instalada pelo administrador sem chaves explícitas de armazenamento gerenciado.
• Em instalações normais, confirme que a integração gerenciada é aplicada quando pelo menos uma chave de política gerenciada está presente.

Solução de problemas

• Política não aplicada: abra chrome://policy ou edge://policy, clique em Recarregar políticas e verifique se não há erros na entrada de política da extensão.
• Extensão ausente após instalação forçada: verifique se foram usados o ID da loja e a URL de atualização corretos e se o perfil foi atribuído à OU ou ao grupo de dispositivos correto.
• Valores gerenciados ignorados: confirme que os nomes das chaves correspondem exatamente ao esquema e que os tipos JSON correspondem ao esquema; booleanos devem ser true/false e strings devem estar entre aspas.
• Valores gerenciados ainda parecem desatualizados: confirme que a extensão foi atualizada, que o service worker está ativo e que o navegador foi reiniciado se valores do Registro ou do perfil mudaram.
• Vozes em nuvem ainda disponíveis após desativar: confirme que EnableCloudVoices está definido como false e que a política aparece como gerenciada em chrome://policy ou edge://policy.

Suporte prioritário: As informações de contato do suporte prioritário estão incluídas no pacote de integração da sua instituição de ensino.