IT-Bereitstellungs- und Konfigurationsleitfaden

Dieses Dokument richtet sich an IT-Administratoren, die HoverSpeak auf Geräten von Bildungseinrichtungen, in Klassenräumen, Laboren oder verwalteten Schülerkonten zwangsweise installieren müssen.

Bereitstellungsvoraussetzungen

• Browserversionen: Chrome 109+ oder Edge 109+ für die aktuelle Erweiterung. HoverSpeak verwendet Manifest-V3-Offscreen-Dokumente über die API chrome.offscreen, die Chrome 109+ / MV3+ erfordert. Die optionale Funktion für Wortdefinitionen erfordert Chrome 148+, da sie auf Chromes neuer lokaler KI-Funktion basiert; Microsoft Edge unterstützt diese Funktion derzeit nicht.
• Von der Erweiterung benötigte Berechtigungen:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Host-Berechtigungen: <all_urls>
• Eintrag für verwaltetes Schema in manifest.json:

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

Modell für verwaltete Richtlinien

• Richtlinien werden in schema.json definiert und über chrome.storage.managed gelesen.
• Effektive Werte werden in dieser Reihenfolge aufgelöst:
  1. Verwaltete Richtlinie
  2. Synchronisierte Benutzereinstellung
  3. Integrierter Standardwert
• Richtlinienschlüssel für Tastenkürzel sind nur Hinweise. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac und PauseShortcutMac aktualisieren die in HoverSpeak angezeigten Tastenkürzelhinweise, erzwingen aber keine Tastenkürzelbindungen in Chrome oder Edge.
• Erkennung verwalteter Einrichtung: HoverSpeak behandelt die Einrichtung als verwaltet, wenn die Erweiterung vom Administrator installiert wurde oder wenn mindestens ein verwalteter Richtlinienschlüssel vorhanden ist. Einstellungen werden nur gesperrt, wenn der entsprechende verwaltete Richtlinienschlüssel tatsächlich gesetzt ist.

Schrittweise erzwungene Installation

Google Admin Console (Chrome)

1. Gehen Sie zu Admin-Konsole → Geräte → Chrome → Apps und Erweiterungen → Nutzer und Browser.
2. Wählen Sie die Ziel-Organisationseinheit (OU) aus.
3. Klicken Sie auf + und fügen Sie die Erweiterung per ID hinzu:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Setzen Sie die Installationsrichtlinie auf Erzwungene Installation.
5. Öffnen Sie die Erweiterungsdetails und konfigurieren Sie Richtlinie → Verwalteter Speicher mit dem JSON-Payload aus dem folgenden Richtlinienabschnitt.
6. Wenden Sie die Richtlinie auf die OU an und warten Sie auf die Verteilung.

Validierung:

• Öffnen Sie auf einem Zielgerät chrome://policy und klicken Sie auf Richtlinien neu laden.
• Bestätigen Sie, dass die Erweiterung in chrome://extensions vorhanden ist.

Microsoft Intune (Edge)

1. Gehen Sie in Microsoft Intune zu Geräte → Konfigurationsprofile und erstellen oder bearbeiten Sie ein Profil für Windows 10 und höher.
2. Verwenden Sie den Einstellungskatalog und fügen Sie diese Einstellung hinzu:
   • Microsoft Edge → Erweiterungen → Einstellungen zur Erweiterungsverwaltung konfigurieren.
3. Fügen Sie einen Eintrag für die erzwungene Installation von Edge mit der Store-ID hinzu:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • Update-URL: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Fügen Sie den JSON-Payload für verwalteten Speicher aus dem Richtlinienabschnitt zum Konfigurationsblock der Erweiterung hinzu.
5. Weisen Sie das Profil der Zielgerätegruppe zu.

Validierung:

• Öffnen Sie auf einem Zielgerät edge://policy und klicken Sie auf Richtlinien neu laden.
• Bestätigen Sie, dass die Erweiterung in edge://extensions vorhanden ist.

Schema für verwaltete Richtlinien (chrome.storage.managed)

Das Schema für verwaltete Richtlinien liegt in schema.json und wird vom Service Worker über chrome.storage.managed gelesen.

Referenz der Richtlinienschlüssel

Alle Schlüssel liegen im Richtlinien-Namespace der Erweiterung und werden schema.json zugeordnet.

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

Beispiel für verwalteten Speicher-Payload

Verwenden Sie dieses JSON im Bereich für verwalteten Speicher der Admin Console oder von 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"
}

Häufige Richtlinienbeispiele

• Verwenden Sie EnableCloudVoices, um Cloud-Stimmen zu erlauben oder zu blockieren. Setzen Sie false, um ausschließlich lokale Stimmen zu erzwingen.
• Für Branding in den Erweiterungseinstellungen setzen Sie OrganizationName und optional OrganizationUrl, um HoverSpeak provided by <name> anzuzeigen.
• Setzen Sie WordByWordHighlightingEnabled, um Word-by-Word ein- oder auszuschalten und zu sperren. Der Auslöseschwellenwert bleibt eine Benutzereinstellung und liegt standardmäßig bei mehr als 40 Wörtern.
• Verwenden Sie ReadShortcut*, StopShortcut* und PauseShortcut* nur als angezeigte Tastenkürzelhinweise. Die Browserzuweisungen bleiben unter Kontrolle von Chrome oder Edge.

Plattformspezifische Bereitstellungshinweise

Windows-Registrierungspfad (Chrome)

Bei Chrome-Bereitstellungen außerhalb der Google Admin Console liest Windows die Erweiterungsrichtlinie aus folgendem Registrierungspfad:

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

• Ersetzen Sie <EXTENSION_ID> durch die HoverSpeak-Erweiterungs-ID aus chrome://extensions.
• Verwenden Sie DWORD (32-bit) für boolesche Schlüssel.
• Verwenden Sie REG_SZ für Zeichenfolgen-Schlüssel.
• Starten Sie Chrome nach Änderungen neu und laden Sie chrome://policy erneut.

Verwaltete macOS-Profile

Unter macOS werden HoverSpeak-Richtlinien über verwaltete Chrome-Konfigurationsprofile bereitgestellt. Verwenden Sie die korrekte Chrome-Bundle-ID und den Richtlinien-Namespace der Erweiterung und laden Sie anschließend chrome://policy neu, um zu bestätigen, dass das Profil aktiv ist.

Validierungscheckliste

• Laden Sie chrome://policy oder edge://policy neu und bestätigen Sie, dass der Richtlinieneintrag keine Parse- oder Typfehler zeigt.
• Bestätigen Sie, dass die Erweiterung in chrome://extensions oder edge://extensions vorhanden und aktualisiert ist.
• Öffnen Sie die HoverSpeak-Einstellungen und bestätigen Sie, dass verwaltete Steuerelemente dort gesperrt sind, wo eine Richtlinie gesetzt ist.
• Bestätigen Sie, dass verwaltete Tooltips oder Beschriftungen für gesperrte Steuerelemente sichtbar sind.
• Prüfen Sie, dass WordByWordHighlightingEnabled=true Word-by-Word aktiviert sperrt, während der unabhängige Wortschwellenwert bearbeitbar bleibt.
• Prüfen Sie, dass ausgewählter Text den konfigurierten Word-by-Word-Schwellenwert überschreiten muss, der standardmäßig bei mehr als 40 Wörtern liegt.
• Prüfen Sie, dass HideDonationAndRating=true den Spenden- und Bewertungsbereich entfernt.
• Prüfen Sie, dass EnableCloudVoices=false Cloud-Stimmen deaktiviert hält.
• Prüfen Sie, dass das Seitenverhalten die verwalteten Einstellungen beim Laden der Seite und nach einer Richtlinienaktualisierung widerspiegelt.
• Prüfen Sie, dass das Organisationsbranding erscheint, wenn OrganizationName konfiguriert ist.
• Bestätigen Sie bei verwalteten Rollouts, dass verwaltetes Onboarding auch dann angewendet wird, wenn die Erweiterung vom Administrator ohne explizite Schlüssel für verwalteten Speicher installiert wurde.
• Bestätigen Sie bei normalen Installationen, dass verwaltetes Onboarding angewendet wird, wenn mindestens ein verwalteter Richtlinienschlüssel vorhanden ist.

Fehlerbehebung

• Richtlinie wird nicht angewendet: Öffnen Sie chrome://policy oder edge://policy, klicken Sie auf Richtlinien neu laden und prüfen Sie, dass im Richtlinieneintrag der Erweiterung keine Fehler angezeigt werden.
• Erweiterung fehlt nach erzwungener Installation: Prüfen Sie, dass die korrekte Store-ID und Update-URL verwendet wurden und das Profil der richtigen OU oder Gerätegruppe zugewiesen ist.
• Verwaltete Werte werden ignoriert: Bestätigen Sie, dass die Schlüsselnamen exakt dem Schema entsprechen und die JSON-Typen zum Schema passen; boolesche Werte müssen true/false sein, Zeichenfolgen müssen in Anführungszeichen stehen.
• Verwaltete Werte wirken weiterhin veraltet: Bestätigen Sie, dass die Erweiterung aktualisiert wurde, der Service Worker aktiv ist und der Browser neu gestartet wurde, falls Registrierungs- oder Profilwerte geändert wurden.
• Cloud-Stimmen sind nach der Deaktivierung weiterhin verfügbar: Stellen Sie sicher, dass EnableCloudVoices auf false gesetzt ist und die Richtlinie in chrome://policy oder edge://policy als verwaltet angezeigt wird.

Priorisierter Support: Kontaktinformationen für priorisierten Support sind im Onboarding-Paket Ihrer Bildungseinrichtung enthalten.