BT Dağıtım ve Yapılandırma Kılavuzu

Bu belge, HoverSpeak’i eğitim kurumu cihazlarında, sınıflarda, laboratuvarlarda veya yönetilen öğrenci hesaplarında zorunlu yüklemesi gereken BT yöneticisi içindir.

Dağıtım ön koşulları

• Tarayıcı sürümleri: Geçerli uzantı için Chrome 109+ veya Edge 109+ gerekir. HoverSpeak, chrome.offscreen API’si üzerinden Manifest V3 offscreen belgelerini kullanır; bunun için Chrome 109+ / MV3+ gerekir. İsteğe bağlı kelime tanımları özelliği, Chrome’un daha yeni yerel AI yeteneğine dayandığı için Chrome 148+ gerektirir; Microsoft Edge şu anda bu özelliği desteklemez.
• Uzantının gerektirdiği izinler:
  • storage (includes managed storage via the schema below)
  • tts
  • scripting
  • offscreen
  • activeTab
  • Ana makine izinleri: <all_urls>
• manifest.json içinde yönetilen şema girdisi:

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

Yönetilen ilke modeli

• İlkeler schema.json içinde tanımlanır ve chrome.storage.managed üzerinden okunur.
• Geçerli değerler şu sırayla belirlenir:
  1. Yönetilen ilke
  2. Kullanıcı eşitleme tercihi
  3. Yerleşik varsayılan
• Kısayol ilke anahtarları yalnızca bilgilendirme amaçlıdır. ReadShortcutWindows, StopShortcutWindows, PauseShortcutWindows, ReadShortcutMac, StopShortcutMac ve PauseShortcutMac, HoverSpeak’in gösterdiği kısayol ipuçlarını günceller; ancak Chrome veya Edge klavye kısayollarını zorla atamaz.
• Yönetilen kurulum algılama: Uzantı yönetici tarafından kurulduğunda veya en az bir yönetilen ilke anahtarı bulunduğunda HoverSpeak kurulumu yönetilen olarak değerlendirir. Ayarlar yalnızca ilgili yönetilen ilke anahtarı gerçekten ayarlandığında kilitlenir.

Adım adım zorunlu kurulum

Google Admin Console (Chrome)

1. Yönetici konsolu → Cihazlar → Chrome → Uygulamalar ve uzantılar → Kullanıcılar ve tarayıcılar yoluna gidin.
2. Hedef kuruluş birimini (OU) seçin.
3. + düğmesine tıklayın ve uzantıyı ID ile ekleyin:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. Kurulum ilkesini Zorunlu kurulum olarak ayarlayın.
5. Uzantı ayrıntılarını açın, ardından İlke → Yönetilen depolama bölümünü aşağıdaki ilke bölümündeki JSON payload ile yapılandırın.
6. İlkeyi OU’ya uygulayın ve yayılmasını bekleyin.

Doğrulama:

• Hedef cihazda chrome://policy sayfasını açın ve İlkeleri yeniden yükle seçeneğine tıklayın.
• Uzantının chrome://extensions içinde bulunduğunu doğrulayın.

Microsoft Intune (Edge)

1. Microsoft Intune içinde Cihazlar → Yapılandırma profilleri bölümüne gidin ve Windows 10 ve sonrası için bir profil oluşturun veya düzenleyin.
2. Ayarlar kataloğunu kullanın ve şu ayarı ekleyin:
   • Microsoft Edge → Uzantılar → Uzantı yönetimi ayarlarını yapılandır.
3. Mağaza ID’sini kullanarak Edge için zorunlu kurulum girdisi ekleyin:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • Güncelleme URL’si: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. İlke bölümündeki yönetilen depolama JSON payload’unu uzantının yapılandırma bloğuna ekleyin.
5. Profili hedef cihaz grubuna atayın.

Doğrulama:

• Hedef cihazda edge://policy sayfasını açın ve İlkeleri yeniden yükle seçeneğine tıklayın.
• Uzantının edge://extensions içinde bulunduğunu doğrulayın.

Yönetilen ilke şeması (chrome.storage.managed)

Yönetilen ilke şeması schema.json içindedir ve service worker tarafından chrome.storage.managed üzerinden okunur.

İlke anahtarı başvurusu

Tüm anahtarlar uzantının ilke ad alanında yer alır ve schema.json ile eşleşir.

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

Yönetilen depolama payload örneği

Bu JSON’u Admin Console veya Intune yönetilen depolama alanında kullanın:

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

Yaygın ilke örnekleri

• Bulut seslerine izin vermek veya engellemek için EnableCloudVoices kullanın. Yalnızca yerel sesleri zorlamak için false ayarlayın.
• Uzantı ayarlarında kurumsal marka göstermek için OrganizationName ve isteğe bağlı olarak OrganizationUrl ayarlayın; böylece HoverSpeak provided by <name> gösterilir.
• Word-by-Word özelliğini açık veya kapalı kilitlemek için WordByWordHighlightingEnabled ayarlayın. Eşik kullanıcı tercihi olarak kalır ve varsayılanı 40 kelimeden fazladır.
• ReadShortcut*, StopShortcut* ve PauseShortcut* anahtarlarını yalnızca görüntülenen kısayol ipuçları olarak kullanın. Tarayıcı kısayol atamaları Chrome veya Edge tarafından yönetilmeye devam eder.

Platforma özel dağıtım notları

Windows Kayıt Defteri yolu (Chrome)

Google Admin Console dışındaki Chrome dağıtımlarında Windows, uzantı ilkesini aşağıdaki kayıt defteri yolundan okur:

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

• <EXTENSION_ID> değerini chrome://extensions içindeki HoverSpeak uzantı ID’siyle değiştirin.
• Boolean anahtarlar için DWORD (32-bit) kullanın.
• Metin anahtarları için REG_SZ kullanın.
• Değişikliklerden sonra Chrome’u yeniden başlatın ve chrome://policy sayfasını yeniden yükleyin.

Yönetilen macOS profilleri

macOS’ta HoverSpeak ilkeleri Chrome yönetilen yapılandırma profilleriyle iletilir. Doğru Chrome bundle ID’sini ve uzantı ilke ad alanını kullanın, ardından profilin etkin olduğunu doğrulamak için chrome://policy sayfasını yeniden yükleyin.

Doğrulama kontrol listesi

• chrome://policy veya edge://policy sayfasını yeniden yükleyin ve ilke girdisinde ayrıştırma ya da tür hatası olmadığını doğrulayın.
• Uzantının chrome://extensions veya edge://extensions içinde bulunduğunu ve güncel olduğunu doğrulayın.
• HoverSpeak ayarlarını açın ve ilke ayarlanan yerlerde yönetilen kontrollerin kilitli olduğunu doğrulayın.
• Kilitli kontroller için yönetilen ipuçlarının veya etiketlerin göründüğünü doğrulayın.
• WordByWordHighlightingEnabled=true değerinin Word-by-Word özelliğini açık kilitlediğini, bağımsız kelime eşiğinin ise düzenlenebilir kaldığını doğrulayın.
• Seçili metnin, varsayılanı 40 kelimeden fazla olan yapılandırılmış Word-by-Word eşiğini aşması gerektiğini doğrulayın.
• HideDonationAndRating=true değerinin bağış ve değerlendirme alanını kaldırdığını doğrulayın.
• EnableCloudVoices=false değerinin bulut seslerini kapalı tuttuğunu doğrulayın.
• Sayfa davranışının, sayfa yüklemesinde ve ilke yenilemesinden sonra yönetilen ayarları yansıttığını doğrulayın.
• OrganizationName yapılandırıldığında kuruluş markasının göründüğünü doğrulayın.
• Yönetilen dağıtımlarda, uzantı açık yönetilen depolama anahtarları olmadan yönetici tarafından kurulmuş olsa bile yönetilen onboarding davranışının uygulandığını doğrulayın.
• Normal kurulumlarda, en az bir yönetilen ilke anahtarı bulunduğunda yönetilen onboarding davranışının uygulandığını doğrulayın.

Sorun giderme

• İlke uygulanmıyor: chrome://policy veya edge://policy sayfasını açın, İlkeleri yeniden yükle seçeneğine tıklayın ve uzantı ilke girdisinde hata olmadığını doğrulayın.
• Zorunlu kurulumdan sonra uzantı eksik: doğru mağaza ID’si ve güncelleme URL’sinin kullanıldığını ve profilin doğru OU’ya veya cihaz grubuna atandığını doğrulayın.
• Yönetilen değerler yok sayılıyor: anahtar adlarının şemayla birebir eşleştiğini ve JSON türlerinin şemaya uyduğunu doğrulayın; boolean değerler true/false olmalı, dizeler tırnak içinde olmalıdır.
• Yönetilen değerler hâlâ eski görünüyor: uzantının güncellendiğini, service worker’ın etkin olduğunu ve kayıt defteri ya da profil değerleri değiştiyse tarayıcının yeniden başlatıldığını doğrulayın.
• Devre dışı bırakıldıktan sonra bulut sesleri hâlâ mevcut: EnableCloudVoices değerinin false olduğunu ve ilkenin chrome://policy veya edge://policy içinde yönetilen olarak göründüğünü doğrulayın.

Öncelikli destek: Öncelikli destek iletişim bilgileri eğitim kurumunuzun başlangıç paketinde yer alır.