Руководство по ИТ-развертыванию и настройке

Этот документ предназначен для ИТ-администратора, которому нужно принудительно установить HoverSpeak на устройства образовательного учреждения, в классы, лаборатории или управляемые учетные записи учащихся.

Предварительные требования к развертыванию

• Версии браузеров: Chrome 109+ или Edge 109+ для текущего расширения. HoverSpeak использует offscreen-документы Manifest V3 через API chrome.offscreen, для чего требуется Chrome 109+ / MV3+. Дополнительная функция определений слов требует Chrome 148+, поскольку использует более новую локальную AI-возможность Chrome; Microsoft Edge сейчас не поддерживает эту функцию.
• Разрешения, требуемые расширением:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Разрешения хоста: <all_urls>
• Запись управляемой схемы в manifest.json:

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

Модель управляемых политик

• Политики определяются в schema.json и читаются через chrome.storage.managed.
• Итоговые значения применяются в таком порядке:
  1. Управляемая политика
  2. Синхронизированная настройка пользователя
  3. Встроенное значение по умолчанию
• Ключи политик сочетаний клавиш носят только рекомендательный характер. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac и PauseShortcutMac обновляют подсказки сочетаний клавиш, отображаемые HoverSpeak, но не принудительно задают сочетания клавиш Chrome или Edge.
• Определение управляемой настройки: HoverSpeak считает настройку управляемой, когда расширение установлено администратором или когда присутствует хотя бы один ключ управляемой политики. Параметры блокируются только тогда, когда задан соответствующий ключ политики.

Пошаговая принудительная установка

Google Admin Console (Chrome)

1. Перейдите в Консоль администратора → Устройства → Chrome → Приложения и расширения → Пользователи и браузеры.
2. Выберите целевое организационное подразделение (OU).
3. Нажмите + и добавьте расширение по ID:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Установите политику установки на Принудительная установка.
5. Откройте сведения о расширении и настройте Политика → Управляемое хранилище с JSON-payload из раздела политик ниже.
6. Примените политику к OU и дождитесь распространения.

Проверка:

• На целевом устройстве откройте chrome://policy и нажмите Перезагрузить политики.
• Убедитесь, что расширение присутствует в chrome://extensions.

Microsoft Intune (Edge)

1. В Microsoft Intune перейдите в Устройства → Профили конфигурации и создайте или измените профиль для Windows 10 и новее.
2. Используйте Каталог параметров и добавьте этот параметр:
   • Microsoft Edge → Расширения → Настроить параметры управления расширениями.
3. Добавьте запись принудительной установки для Edge, используя ID магазина:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • URL обновления: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. Добавьте JSON-payload управляемого хранилища из раздела политик в блок конфигурации расширения.
5. Назначьте профиль целевой группе устройств.

Проверка:

• На целевом устройстве откройте edge://policy и нажмите Перезагрузить политики.
• Убедитесь, что расширение присутствует в edge://extensions.

Схема управляемой политики (chrome.storage.managed)

Схема управляемой политики находится в schema.json и читается service worker через chrome.storage.managed.

Справочник ключей политик

Все ключи относятся к пространству имен политик расширения и сопоставляются с 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."
    }
  }
}

Пример payload управляемого хранилища

Используйте этот JSON в области управляемого хранилища Admin Console или 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"
}

Распространенные примеры политик

• Используйте EnableCloudVoices, чтобы разрешить или заблокировать облачные голоса. Установите false, чтобы принудительно использовать только локальные голоса.
• Для брендинга в настройках расширения задайте OrganizationName и при необходимости OrganizationUrl, чтобы показать HoverSpeak provided by <name>.
• Установите WordByWordHighlightingEnabled, чтобы заблокировать Word-by-Word включенным или выключенным. Порог остается пользовательской настройкой и по умолчанию составляет более 40 слов.
• Используйте ReadShortcut*, StopShortcut* и PauseShortcut* только как отображаемые подсказки сочетаний клавиш. Назначения браузера остаются под управлением Chrome или Edge.

Примечания к развертыванию по платформам

Путь реестра Windows (Chrome)

Для развертываний Chrome вне Google Admin Console Windows считывает политику расширения из указанного ниже пути реестра:

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

• Замените <EXTENSION_ID> на ID расширения HoverSpeak из chrome://extensions.
• Используйте DWORD (32-bit) для логических ключей.
• Используйте REG_SZ для строковых ключей.
• После внесения изменений перезапустите Chrome и перезагрузите chrome://policy.

Управляемые профили macOS

В macOS политики HoverSpeak доставляются через управляемые профили конфигурации Chrome. Используйте правильный идентификатор пакета Chrome и пространство имен политики расширения, затем перезагрузите chrome://policy, чтобы подтвердить активность профиля.

Контрольный список проверки

• Перезагрузите chrome://policy или edge://policy и убедитесь, что запись политики не показывает ошибок разбора или типа.
• Убедитесь, что расширение присутствует и обновлено в chrome://extensions или edge://extensions.
• Откройте настройки HoverSpeak и убедитесь, что управляемые элементы управления заблокированы там, где задана политика.
• Убедитесь, что для заблокированных элементов управления видны управляемые подсказки или метки.
• Проверьте, что WordByWordHighlightingEnabled=true блокирует Word-by-Word включенным, а отдельный порог слов остается редактируемым.
• Проверьте, что выделенный текст должен превышать настроенный порог Word-by-Word, который по умолчанию составляет более 40 слов.
• Проверьте, что HideDonationAndRating=true удаляет область пожертвований и оценок.
• Проверьте, что EnableCloudVoices=false оставляет облачные голоса отключенными.
• Проверьте, что поведение страницы отражает управляемые настройки при загрузке и после обновления политики.
• Проверьте, что брендинг организации появляется при настроенном OrganizationName.
• Для управляемых развертываний убедитесь, что управляемый onboarding применяется даже при установке расширения администратором без явных ключей управляемого хранилища.
• Для обычных установок убедитесь, что управляемый onboarding применяется при наличии хотя бы одного ключа управляемой политики.

Устранение неполадок

• Политика не применяется: откройте chrome://policy или edge://policy, нажмите Перезагрузить политики и убедитесь, что в записи политики расширения нет ошибок.
• Расширение отсутствует после принудительной установки: проверьте правильность ID магазина и URL обновления, а также назначение профиля правильной OU или группе устройств.
• Управляемые значения игнорируются: убедитесь, что имена ключей точно соответствуют схеме, а типы JSON соответствуют схеме; логические значения должны быть true/false, строки должны быть в кавычках.
• Управляемые значения все еще выглядят устаревшими: убедитесь, что расширение обновлено, service worker активен, а браузер перезапущен, если изменялись значения реестра или профиля.
• Облачные голоса все еще доступны после отключения: убедитесь, что EnableCloudVoices установлен в false, а политика отображается как управляемая в chrome://policy или edge://policy.

Приоритетная поддержка: Контактная информация приоритетной поддержки включена в пакет внедрения для вашего образовательного учреждения.