IT Deployment & Configuration Guide

This document is for the IT administrator who needs to force-install HoverSpeak across educational institution devices, classrooms, labs, or managed student accounts.

Deployment Prerequisites

• Browser versions: Chrome 109+ or Edge 109+ for the current extension. HoverSpeak uses Manifest V3 offscreen documents through the chrome.offscreen API, which requires Chrome 109+ / MV3+. The optional Word definitions feature requires Chrome 148+ because it relies on Chrome's newer local AI capability; Microsoft Edge does not currently support that definitions feature.
• Permissions required by the extension:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Host permissions: <all_urls>
• Managed schema entry in manifest.json:

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

Managed Policy Model

• Policies are defined in schema.json and read via chrome.storage.managed.
• Effective values resolve in this order:
  1. Managed policy
  2. User sync preference
  3. Built-in default
• Shortcut policy keys are advisory only. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac, and PauseShortcutMac update HoverSpeak's displayed shortcut hints, but they do not force Chrome or Edge keyboard shortcut bindings.
• Managed setup detection: HoverSpeak treats the setup as managed when the extension is admin-installed or when at least one managed policy key is present. Settings are only locked when the corresponding managed policy key is actually set.

Step-by-step Force Install

Google Admin Console (Chrome)

1. Go to Admin console → Devices → Chrome → Apps & extensions → Users & browsers.
2. Select the target organizational unit (OU).
3. Click + and add the extension by ID:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Set the install policy to Force install.
5. Open the extension details, then configure Policy → Managed storage with the JSON payload from the policy section below.
6. Apply the policy to the OU and wait for policy propagation.

Validation:

• On a target device, open chrome://policy and click Reload policies.
• Confirm the extension is present in chrome://extensions.

Microsoft Intune (Edge)

1. In Microsoft Intune, go to Devices → Configuration profiles and create or edit a profile for Windows 10 and later.
2. Use Settings catalog and add the setting:
   • Microsoft Edge → Extensions → Configure extension management settings.
3. Add a force-install entry for Edge using the store ID:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • Update URL: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Add the managed storage JSON payload from the policy section below to the extension's configuration block.
5. Assign the profile to the target device group.

Validation:

• On a target device, open edge://policy and click Reload policies.
• Confirm the extension is present in edge://extensions.

Managed Policy Schema (chrome.storage.managed)

The managed policy schema lives in schema.json and is read by the service worker via chrome.storage.managed.

Policy Key Reference

All keys live under the extension policy namespace and map to 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."
    }
  }
}

Managed Storage Payload Example

Use this JSON in the Admin Console or Intune managed storage area:

{
  "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"
}

Common Policy Examples

• Use EnableCloudVoices to allow or block cloud voices. Set it to false to force local-only voices.
• To brand the extension in the extension settings interface, set OrganizationName (and optionally OrganizationUrl) to show "HoverSpeak provided by <name>".
• Set WordByWordHighlightingEnabled to lock the Word-by-Word feature toggle on or off. The trigger threshold remains a user preference and defaults to more than 40 words.
• Use ReadShortcut*, StopShortcut*, and PauseShortcut* keys only as displayed shortcut hints. Browser shortcut assignments remain controlled by Chrome or Edge.

Platform-specific Deployment Notes

Windows Registry Path (Chrome)

For Chrome deployments outside Google Admin Console, Windows reads extension policy from the registry path below:

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

• Replace <EXTENSION_ID> with the HoverSpeak extension ID from chrome://extensions.
• Use DWORD (32-bit) for boolean keys.
• Use REG_SZ for string keys.
• After making changes, restart Chrome and reload chrome://policy.

macOS Managed Profiles

On macOS, HoverSpeak policies are delivered through Chrome managed configuration profiles. Use the correct Chrome bundle identifier and the extension policy namespace, then reload policies at chrome://policy to confirm the profile is active.

Validation Checklist

• Reload chrome://policy or edge://policy and confirm the policy entry shows no parse or type errors.
• Confirm the extension is present and updated in chrome://extensions or edge://extensions.
• Open the HoverSpeak extension settings interface and confirm managed controls are actually locked where policy is set.
• Confirm managed tooltips or labels are visible for locked controls.
• Verify WordByWordHighlightingEnabled=true locks the Word-by-Word toggle on while the independent word threshold remains editable.
• Verify selected text must exceed the configured Word-by-Word threshold, which defaults to more than 40 words.
• Verify HideDonationAndRating=true removes the donation and rating area.
• Verify EnableCloudVoices=false keeps cloud voices disabled.
• Verify page behavior reflects managed settings on page load and after a policy refresh.
• Verify organization branding appears when OrganizationName is configured.
• For managed-setup rollouts, confirm managed onboarding behavior is applied even when the extension is admin-installed without explicit managed storage keys.
• For normal installs, confirm managed onboarding behavior is applied when at least one managed policy key is present.

Troubleshooting

• Policy not applying: open chrome://policy or edge://policy, click Reload policies, and verify there are no errors on the extension policy entry.
• Extension missing after force install: verify the correct store ID and update URL were used and the profile is assigned to the correct OU/device group.
• Managed values ignored: confirm the key names match the schema exactly and the JSON types match the schema (booleans must be true/false, strings must be quoted).
• Managed values still appear stale: confirm the extension has updated, the service worker is active, and the browser was restarted if registry or profile values changed.
• Cloud voices still available after disabling: ensure EnableCloudVoices is set to false and the policy is showing as managed in chrome://policy or edge://policy.

Priority Support: Priority support contact information is included in your educational institution onboarding package.