Guida alla distribuzione e configurazione IT

Questo documento è per l’amministratore IT che deve installare forzatamente HoverSpeak su dispositivi scolastici, classi, laboratori o account studenti gestiti.

Prerequisiti di distribuzione

• Versioni del browser: Chrome 109+ o Edge 109+ per l’estensione attuale. HoverSpeak usa documenti offscreen di Manifest V3 tramite l’API chrome.offscreen, che richiede Chrome 109+ / MV3+. La funzione opzionale di definizione delle parole richiede Chrome 148+ perché si basa sulla nuova capacità AI locale di Chrome; Microsoft Edge al momento non supporta questa funzione.
• Autorizzazioni richieste dall’estensione:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Autorizzazioni host: <all_urls>
• Voce schema gestito in manifest.json:

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

Modello di criteri gestiti

• I criteri sono definiti in schema.json e letti tramite chrome.storage.managed.
• I valori effettivi vengono risolti in questo ordine:
  1. Criterio gestito
  2. Preferenza sincronizzata dell’utente
  3. Valore predefinito integrato
• Le chiavi dei criteri per le scorciatoie sono solo indicative. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac e PauseShortcutMac aggiornano i suggerimenti di scorciatoia mostrati da HoverSpeak, ma non impongono le scorciatoie da tastiera di Chrome o Edge.
• Rilevamento della configurazione gestita: HoverSpeak considera la configurazione gestita quando l’estensione è installata da un amministratore o quando è presente almeno una chiave di criterio gestito. Le impostazioni vengono bloccate solo quando la chiave di criterio corrispondente è impostata.

Installazione forzata passo per passo

Google Admin Console (Chrome)

1. Vai a Console di amministrazione → Dispositivi → Chrome → App ed estensioni → Utenti e browser.
2. Seleziona l’unità organizzativa (OU) di destinazione.
3. Fai clic su + e aggiungi l’estensione tramite ID:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Imposta il criterio di installazione su Installazione forzata.
5. Apri i dettagli dell’estensione, quindi configura Criterio → Archiviazione gestita con il payload JSON della sezione criteri qui sotto.
6. Applica il criterio all’OU e attendi la propagazione.

Convalida:

• Su un dispositivo di destinazione, apri chrome://policy e fai clic su Ricarica criteri.
• Conferma che l’estensione sia presente in chrome://extensions.

Microsoft Intune (Edge)

1. In Microsoft Intune, vai a Dispositivi → Profili di configurazione e crea o modifica un profilo per Windows 10 e versioni successive.
2. Usa il Catalogo impostazioni e aggiungi questa impostazione:
   • Microsoft Edge → Estensioni → Configura le impostazioni di gestione delle estensioni.
3. Aggiungi una voce di installazione forzata per Edge usando l’ID dello store:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • URL di aggiornamento: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Aggiungi il payload JSON di archiviazione gestita dalla sezione criteri al blocco di configurazione dell’estensione.
5. Assegna il profilo al gruppo di dispositivi di destinazione.

Convalida:

• Su un dispositivo di destinazione, apri edge://policy e fai clic su Ricarica criteri.
• Conferma che l’estensione sia presente in edge://extensions.

Schema dei criteri gestiti (chrome.storage.managed)

Lo schema dei criteri gestiti si trova in schema.json ed è letto dal service worker tramite chrome.storage.managed.

Riferimento delle chiavi dei criteri

Tutte le chiavi appartengono allo spazio dei nomi dei criteri dell’estensione e corrispondono 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."
    }
  }
}

Esempio di payload di archiviazione gestita

Usa questo JSON nell’area di archiviazione gestita di 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"
}

Esempi comuni di criteri

• Usa EnableCloudVoices per consentire o bloccare le voci cloud. Imposta false per forzare solo voci locali.
• Per mostrare il branding nelle impostazioni dell’estensione, imposta OrganizationName e, facoltativamente, OrganizationUrl per visualizzare HoverSpeak provided by <name>.
• Imposta WordByWordHighlightingEnabled per bloccare Word-by-Word attivo o disattivo. La soglia resta una preferenza utente e il valore predefinito è più di 40 parole.
• Usa ReadShortcut*, StopShortcut* e PauseShortcut* solo come suggerimenti di scorciatoie visualizzati. Le assegnazioni del browser restano controllate da Chrome o Edge.

Note di distribuzione specifiche della piattaforma

Percorso del Registro di Windows (Chrome)

Per distribuzioni Chrome fuori da Google Admin Console, Windows legge il criterio dell’estensione dal percorso del Registro seguente:

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

• Sostituisci <EXTENSION_ID> con l’ID dell’estensione HoverSpeak da chrome://extensions.
• Usa DWORD (32-bit) per chiavi booleane.
• Usa REG_SZ per chiavi di testo.
• Dopo le modifiche, riavvia Chrome e ricarica chrome://policy.

Profili gestiti macOS

Su macOS, i criteri HoverSpeak vengono distribuiti tramite profili di configurazione gestita di Chrome. Usa l’identificatore bundle corretto di Chrome e lo spazio dei nomi dei criteri dell’estensione, quindi ricarica chrome://policy per confermare che il profilo sia attivo.

Checklist di convalida

• Ricarica chrome://policy o edge://policy e conferma che la voce del criterio non mostri errori di parsing o di tipo.
• Conferma che l’estensione sia presente e aggiornata in chrome://extensions o edge://extensions.
• Apri le impostazioni di HoverSpeak e conferma che i controlli gestiti siano bloccati dove il criterio è impostato.
• Conferma che suggerimenti o etichette gestite siano visibili per i controlli bloccati.
• Verifica che WordByWordHighlightingEnabled=true blocchi Word-by-Word attivo mentre la soglia indipendente di parole resta modificabile.
• Verifica che il testo selezionato debba superare la soglia configurata di Word-by-Word, che per impostazione predefinita è più di 40 parole.
• Verifica che HideDonationAndRating=true rimuova l’area donazione e valutazione.
• Verifica che EnableCloudVoices=false mantenga disattivate le voci cloud.
• Verifica che il comportamento della pagina rifletta le impostazioni gestite al caricamento e dopo un aggiornamento dei criteri.
• Verifica che il branding dell’organizzazione appaia quando OrganizationName è configurato.
• Per distribuzioni gestite, conferma che l’onboarding gestito venga applicato anche quando l’estensione è installata da amministratore senza chiavi esplicite di archiviazione gestita.
• Per installazioni normali, conferma che l’onboarding gestito venga applicato quando è presente almeno una chiave di criterio gestito.

Risoluzione dei problemi

• Criterio non applicato: apri chrome://policy o edge://policy, fai clic su Ricarica criteri e verifica che non ci siano errori nella voce criterio dell’estensione.
• Estensione mancante dopo l’installazione forzata: verifica che siano stati usati l’ID store e l’URL di aggiornamento corretti e che il profilo sia assegnato alla OU o al gruppo dispositivi corretto.
• Valori gestiti ignorati: conferma che i nomi delle chiavi corrispondano esattamente allo schema e che i tipi JSON corrispondano allo schema; i booleani devono essere true/false e le stringhe tra virgolette.
• I valori gestiti risultano ancora obsoleti: conferma che l’estensione sia aggiornata, che il service worker sia attivo e che il browser sia stato riavviato se sono cambiati valori del Registro o del profilo.
• Le voci cloud sono ancora disponibili dopo la disattivazione: assicurati che EnableCloudVoices sia impostato su false e che il criterio risulti gestito in chrome://policy o edge://policy.

Supporto prioritario: Le informazioni di contatto per il supporto prioritario sono incluse nel pacchetto di onboarding dell’istituto.