IT-implementatie- en configuratiegids

Dit document is bedoeld voor de IT-beheerder die HoverSpeak geforceerd moet installeren op apparaten van onderwijsinstellingen, klaslokalen, labs of beheerde leerlingaccounts.

Implementatievereisten

• Browserversies: Chrome 109+ of Edge 109+ voor de huidige extensie. HoverSpeak gebruikt Manifest V3-offscreen-documenten via de API chrome.offscreen, waarvoor Chrome 109+ / MV3+ nodig is. De optionele functie voor woorddefinities vereist Chrome 148+, omdat deze steunt op de nieuwere lokale AI-mogelijkheid van Chrome; Microsoft Edge ondersteunt deze functie momenteel niet.
• Door de extensie vereiste machtigingen:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Hostmachtigingen: <all_urls>
• Beheerde schema-invoer in manifest.json:

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

Model voor beheerd beleid

• Beleid wordt gedefinieerd in schema.json en gelezen via chrome.storage.managed.
• Effectieve waarden worden in deze volgorde bepaald:
  1. Beheerd beleid
  2. Gesynchroniseerde gebruikersvoorkeur
  3. Ingebouwde standaardwaarde
• Beleidssleutels voor sneltoetsen zijn alleen adviserend. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac en PauseShortcutMac werken de sneltoetshints bij die HoverSpeak toont, maar dwingen geen sneltoetsen in Chrome of Edge af.
• Detectie van beheerde configuratie: HoverSpeak behandelt de installatie als beheerd wanneer de extensie door een beheerder is geïnstalleerd of wanneer ten minste één beheerde beleidssleutel aanwezig is. Instellingen worden alleen vergrendeld wanneer de bijbehorende beleidssleutel daadwerkelijk is ingesteld.

Geforceerde installatie stap voor stap

Google Admin Console (Chrome)

1. Ga naar Beheerdersconsole → Apparaten → Chrome → Apps en extensies → Gebruikers en browsers.
2. Selecteer de doelorganisatie-eenheid (OU).
3. Klik op + en voeg de extensie toe op ID:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Stel het installatiebeleid in op Geforceerd installeren.
5. Open de extensiedetails en configureer Beleid → Beheerde opslag met de JSON-payload uit de beleidssectie hieronder.
6. Pas het beleid toe op de OU en wacht op propagatie.

Validatie:

• Open op een doelapparaat chrome://policy en klik op Beleid opnieuw laden.
• Bevestig dat de extensie aanwezig is in chrome://extensions.

Microsoft Intune (Edge)

1. Ga in Microsoft Intune naar Apparaten → Configuratieprofielen en maak of bewerk een profiel voor Windows 10 en later.
2. Gebruik de Instellingencatalogus en voeg deze instelling toe:
   • Microsoft Edge → Extensies → Instellingen voor extensiebeheer configureren.
3. Voeg een geforceerde-installatievermelding voor Edge toe met de store-ID:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • Update-URL: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Voeg de JSON-payload voor beheerde opslag uit de beleidssectie toe aan het configuratieblok van de extensie.
5. Wijs het profiel toe aan de doelapparaatgroep.

Validatie:

• Open op een doelapparaat edge://policy en klik op Beleid opnieuw laden.
• Bevestig dat de extensie aanwezig is in edge://extensions.

Schema voor beheerd beleid (chrome.storage.managed)

Het schema voor beheerd beleid staat in schema.json en wordt door de service worker gelezen via chrome.storage.managed.

Referentie voor beleidssleutels

Alle sleutels vallen onder de beleidsnaamruimte van de extensie en verwijzen naar 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."
    }
  }
}

Voorbeeld van beheerde opslagpayload

Gebruik deze JSON in het beheerde opslaggebied van Admin Console of 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"
}

Veelvoorkomende beleidsvoorbeelden

• Gebruik EnableCloudVoices om cloudstemmen toe te staan of te blokkeren. Stel false in om alleen lokale stemmen af te dwingen.
• Stel voor branding in de extensie-instellingen OrganizationName en optioneel OrganizationUrl in om HoverSpeak provided by <name> te tonen.
• Stel WordByWordHighlightingEnabled in om Word-by-Word aan of uit te vergrendelen. De drempel blijft een gebruikersvoorkeur en is standaard meer dan 40 woorden.
• Gebruik ReadShortcut*, StopShortcut* en PauseShortcut* alleen als weergegeven sneltoetshints. Browsertoewijzingen blijven door Chrome of Edge beheerd.

Platformspecifieke implementatieopmerkingen

Windows-registerpad (Chrome)

Voor Chrome-implementaties buiten Google Admin Console leest Windows het extensiebeleid uit het onderstaande registerpad:

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

• Vervang <EXTENSION_ID> door de HoverSpeak-extensie-ID uit chrome://extensions.
• Gebruik DWORD (32-bit) voor booleaanse sleutels.
• Gebruik REG_SZ voor tekenreekssleutels.
• Start Chrome na wijzigingen opnieuw en laad chrome://policy opnieuw.

Beheerde macOS-profielen

Op macOS worden HoverSpeak-beleidsregels geleverd via beheerde Chrome-configuratieprofielen. Gebruik de juiste Chrome-bundle-ID en beleidsnaamruimte van de extensie en laad daarna chrome://policy opnieuw om te bevestigen dat het profiel actief is.

Validatiechecklist

• Laad chrome://policy of edge://policy opnieuw en bevestig dat de beleidsvermelding geen parse- of typefouten toont.
• Bevestig dat de extensie aanwezig en bijgewerkt is in chrome://extensions of edge://extensions.
• Open de HoverSpeak-instellingen en bevestig dat beheerde controles zijn vergrendeld waar beleid is ingesteld.
• Bevestig dat beheerde tooltips of labels zichtbaar zijn voor vergrendelde controles.
• Controleer dat WordByWordHighlightingEnabled=true Word-by-Word ingeschakeld vergrendelt terwijl de afzonderlijke woorddrempel bewerkbaar blijft.
• Controleer dat geselecteerde tekst de ingestelde Word-by-Word-drempel moet overschrijden, standaard meer dan 40 woorden.
• Controleer dat HideDonationAndRating=true het donatie- en beoordelingsgedeelte verwijdert.
• Controleer dat EnableCloudVoices=false cloudstemmen uitgeschakeld houdt.
• Controleer dat paginagedrag de beheerde instellingen weerspiegelt bij het laden en na een beleidsvernieuwing.
• Controleer dat organisatiebranding verschijnt wanneer OrganizationName is geconfigureerd.
• Bevestig bij beheerde uitrol dat beheerde onboarding wordt toegepast, ook wanneer de extensie door een beheerder is geïnstalleerd zonder expliciete sleutels voor beheerde opslag.
• Bevestig bij normale installaties dat beheerde onboarding wordt toegepast wanneer ten minste één beheerde beleidssleutel aanwezig is.

Probleemoplossing

• Beleid wordt niet toegepast: open chrome://policy of edge://policy, klik op Beleid opnieuw laden en controleer of er geen fouten staan bij de beleidsvermelding van de extensie.
• Extensie ontbreekt na geforceerde installatie: controleer of de juiste store-ID en update-URL zijn gebruikt en of het profiel is toegewezen aan de juiste OU of apparaatgroep.
• Beheerde waarden worden genegeerd: bevestig dat de sleutelnamen exact overeenkomen met het schema en dat de JSON-typen kloppen; booleans moeten true/false zijn en tekenreeksen moeten tussen aanhalingstekens staan.
• Beheerde waarden lijken nog verouderd: bevestig dat de extensie is bijgewerkt, de service worker actief is en de browser is herstart als register- of profielwaarden zijn gewijzigd.
• Cloudstemmen blijven beschikbaar na uitschakeling: zorg dat EnableCloudVoices op false staat en dat het beleid als beheerd wordt weergegeven in chrome://policy of edge://policy.

Prioritaire ondersteuning: Contactgegevens voor prioritaire ondersteuning zijn opgenomen in het onboardingpakket van uw onderwijsinstelling.