Guía de implementación y configuración de TI

Este documento es para el administrador de TI que necesita forzar la instalación de HoverSpeak en dispositivos de instituciones educativas, aulas, laboratorios o cuentas de estudiantes administradas.

Requisitos previos de implementación

• Versiones del navegador: Chrome 109+ o Edge 109+ para la extensión actual. HoverSpeak usa documentos fuera de pantalla de Manifest V3 mediante la API chrome.offscreen, que requiere Chrome 109+ / MV3+. La función opcional de definiciones de palabras requiere Chrome 148+ porque depende de la capacidad local de IA más reciente de Chrome; Microsoft Edge no admite actualmente esa función.
• Permisos requeridos por la extensión:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Permisos de host: <all_urls>
• Entrada de esquema administrado en manifest.json:

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

Modelo de política administrada

• Las políticas se definen en schema.json y se leen mediante chrome.storage.managed.
• Los valores efectivos se resuelven en este orden:
  1. Política administrada
  2. Preferencia sincronizada del usuario
  3. Valor predeterminado integrado
• Las claves de política de accesos directos son solo orientativas. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac y PauseShortcutMac actualizan las indicaciones de accesos directos que muestra HoverSpeak, pero no fuerzan las combinaciones de teclas de Chrome o Edge.
• Detección de configuración administrada: HoverSpeak considera la instalación como administrada cuando la extensión se instala por un administrador o cuando existe al menos una clave de política administrada. Los ajustes solo se bloquean cuando la clave de política correspondiente está definida.

Instalación forzada paso a paso

Google Admin Console (Chrome)

1. Vaya a Consola de administración → Dispositivos → Chrome → Aplicaciones y extensiones → Usuarios y navegadores.
2. Seleccione la unidad organizativa (OU) de destino.
3. Haga clic en + y añada la extensión por ID:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Establezca la política de instalación en Forzar instalación.
5. Abra los detalles de la extensión y configure Política → Almacenamiento administrado con el payload JSON de la sección de políticas siguiente.
6. Aplique la política a la OU y espere la propagación.

Validación:

• En un dispositivo de destino, abra chrome://policy y haga clic en Volver a cargar políticas.
• Confirme que la extensión aparece en chrome://extensions.

Microsoft Intune (Edge)

1. En Microsoft Intune, vaya a Dispositivos → Perfiles de configuración y cree o edite un perfil para Windows 10 y versiones posteriores.
2. Use Catálogo de configuración y agregue este ajuste:
   • Microsoft Edge → Extensiones → Configurar opciones de administración de extensiones.
3. Agregue una entrada de instalación forzada para Edge usando el ID de la tienda:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • URL de actualización: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Agregue el payload JSON de almacenamiento administrado de la sección de políticas al bloque de configuración de la extensión.
5. Asigne el perfil al grupo de dispositivos de destino.

Validación:

• En un dispositivo de destino, abra edge://policy y haga clic en Volver a cargar políticas.
• Confirme que la extensión aparece en edge://extensions.

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

El esquema de política administrada vive en schema.json y el service worker lo lee mediante chrome.storage.managed.

Referencia de claves de política

Todas las claves pertenecen al espacio de nombres de políticas de la extensión y se asignan 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."
    }
  }
}

Ejemplo de payload de almacenamiento administrado

Use este JSON en el área de almacenamiento administrado de Admin Console o 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"
}

Ejemplos comunes de políticas

• Use EnableCloudVoices para permitir o bloquear voces en la nube. Defínalo en false para forzar voces solo locales.
• Para mostrar la marca en los ajustes de la extensión, defina OrganizationName y opcionalmente OrganizationUrl para mostrar HoverSpeak provided by <name>.
• Defina WordByWordHighlightingEnabled para bloquear Word-by-Word activado o desactivado. El umbral sigue siendo una preferencia del usuario y por defecto es más de 40 palabras.
• Use ReadShortcut*, StopShortcut* y PauseShortcut* solo como indicaciones visibles de accesos directos. Las asignaciones del navegador siguen controladas por Chrome o Edge.

Notas de implementación específicas de la plataforma

Ruta del Registro de Windows (Chrome)

Para implementaciones de Chrome fuera de Google Admin Console, Windows lee la política de la extensión desde la ruta del Registro siguiente:

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

• Sustituya <EXTENSION_ID> por el ID de la extensión HoverSpeak de chrome://extensions.
• Use DWORD (32-bit) para claves booleanas.
• Use REG_SZ para claves de texto.
• Después de hacer cambios, reinicie Chrome y vuelva a cargar chrome://policy.

Perfiles administrados de macOS

En macOS, las políticas de HoverSpeak se entregan mediante perfiles de configuración administrada de Chrome. Use el identificador de paquete correcto de Chrome y el espacio de nombres de política de la extensión; luego vuelva a cargar chrome://policy para confirmar que el perfil está activo.

Lista de validación

• Vuelva a cargar chrome://policy o edge://policy y confirme que la entrada de política no muestra errores de análisis ni de tipo.
• Confirme que la extensión está presente y actualizada en chrome://extensions o edge://extensions.
• Abra los ajustes de HoverSpeak y confirme que los controles administrados están bloqueados donde se definió una política.
• Confirme que las etiquetas o ayudas de controles administrados aparecen para los controles bloqueados.
• Compruebe que WordByWordHighlightingEnabled=true bloquea Word-by-Word activado mientras el umbral independiente de palabras sigue siendo editable.
• Compruebe que el texto seleccionado debe superar el umbral configurado de Word-by-Word, que por defecto es más de 40 palabras.
• Compruebe que HideDonationAndRating=true elimina el área de donación y valoración.
• Compruebe que EnableCloudVoices=false mantiene desactivadas las voces en la nube.
• Compruebe que el comportamiento de la página refleja los ajustes administrados al cargar la página y después de actualizar políticas.
• Compruebe que la marca de la organización aparece cuando OrganizationName está configurado.
• En implementaciones administradas, confirme que la incorporación administrada se aplica incluso cuando la extensión se instaló por administrador sin claves explícitas de almacenamiento administrado.
• En instalaciones normales, confirme que la incorporación administrada se aplica cuando existe al menos una clave de política administrada.

Solución de problemas

• La política no se aplica: abra chrome://policy o edge://policy, haga clic en Volver a cargar políticas y compruebe que no haya errores en la entrada de política de la extensión.
• La extensión falta tras la instalación forzada: compruebe que se usaron el ID de tienda y la URL de actualización correctos y que el perfil está asignado a la OU o grupo de dispositivos correcto.
• Los valores administrados se ignoran: confirme que los nombres de clave coinciden exactamente con el esquema y que los tipos JSON coinciden con el esquema; los booleanos deben ser true/false y las cadenas deben ir entre comillas.
• Los valores administrados siguen desactualizados: confirme que la extensión se actualizó, que el service worker está activo y que el navegador se reinició si cambiaron valores del Registro o del perfil.
• Las voces en la nube siguen disponibles tras desactivarlas: asegúrese de que EnableCloudVoices esté en false y que la política aparezca como administrada en chrome://policy o edge://policy.

Soporte prioritario: La información de contacto del soporte prioritario se incluye en el paquete de incorporación de la institución educativa.