دليل النشر والتكوين لتقنية المعلومات

هذا المستند مخصص لمسؤول تقنية المعلومات الذي يحتاج إلى تثبيت HoverSpeak إجباريًا على أجهزة المؤسسات التعليمية أو الفصول أو المختبرات أو حسابات الطلاب المُدارة.

متطلبات النشر المسبقة

• إصدارات المتصفح: Chrome 109+ أو Edge 109+ للإضافة الحالية. يستخدم HoverSpeak مستندات Manifest V3 خارج الشاشة عبر واجهة chrome.offscreen التي تتطلب Chrome 109+ / MV3+. تتطلب ميزة تعريفات الكلمات الاختيارية Chrome 148+ لأنها تعتمد على قدرة الذكاء الاصطناعي المحلية الأحدث في 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. انقر على + وأضف الإضافة باستخدام المعرّف:
   • Chrome Web Store ID: kpkdjcalihjnkemhkdlciiekkmooglmb
4. اضبط سياسة التثبيت على تثبيت إجباري.
5. افتح تفاصيل الإضافة ثم كوّن السياسة ← التخزين المُدار باستخدام حمولة JSON من قسم السياسات أدناه.
6. طبّق السياسة على الوحدة التنظيمية وانتظر انتشارها.

التحقق:

• على جهاز مستهدف، افتح chrome://policy وانقر على إعادة تحميل السياسات.
• تأكد من وجود الإضافة في chrome://extensions.

Microsoft Intune (Edge)

1. في Microsoft Intune، انتقل إلى الأجهزة ← ملفات تعريف التكوين وأنشئ أو عدّل ملفًا شخصيًا لـ Windows 10 والإصدارات الأحدث.
2. استخدم كتالوج الإعدادات وأضف هذا الإعداد:
   • Microsoft Edge ← الإضافات ← تكوين إعدادات إدارة الإضافات.
3. أضف إدخال تثبيت إجباري لـ Edge باستخدام معرّف المتجر:
   • Edge Add-ons ID: omibkefgmhnhfboefblahmjdcgapoeea
   • عنوان URL للتحديث: https://edge.microsoft.com/extensionwebstorebase/v1/crx
4. أضف حمولة JSON للتخزين المُدار من قسم السياسات إلى كتلة تكوين الإضافة.
5. عيّن ملف التعريف إلى مجموعة الأجهزة المستهدفة.

التحقق:

• على جهاز مستهدف، افتح edge://policy وانقر على إعادة تحميل السياسات.
• تأكد من وجود الإضافة في edge://extensions.

مخطط السياسة المُدارة (chrome.storage.managed)

يوجد مخطط السياسة المُدارة في schema.json ويقرأه عامل الخدمة عبر 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."
    }
  }
}

مثال حمولة التخزين المُدار

استخدم ملف 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> بمعرّف إضافة 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.
• في عمليات النشر المُدارة، تأكد من تطبيق تجربة الإعداد المُدارة حتى عندما يتم تثبيت الإضافة بواسطة المسؤول دون مفاتيح تخزين مُدار صريحة.
• في عمليات التثبيت العادية، تأكد من تطبيق تجربة الإعداد المُدارة عند وجود مفتاح سياسة مُدارة واحد على الأقل.

استكشاف الأخطاء وإصلاحها

• السياسة لا تُطبّق: افتح chrome://policy أو edge://policy، وانقر على إعادة تحميل السياسات، وتحقق من عدم وجود أخطاء في إدخال سياسة الإضافة.
• الإضافة مفقودة بعد التثبيت الإجباري: تحقق من استخدام معرّف المتجر وعنوان URL للتحديث الصحيحين ومن تعيين ملف التعريف إلى الوحدة التنظيمية أو مجموعة الأجهزة الصحيحة.
• يتم تجاهل القيم المُدارة: تأكد من أن أسماء المفاتيح تطابق المخطط تمامًا وأن أنواع JSON تطابق المخطط؛ يجب أن تكون القيم المنطقية true/false وأن تكون السلاسل النصية بين علامتي اقتباس.
• لا تزال القيم المُدارة تبدو قديمة: تأكد من تحديث الإضافة ونشاط عامل الخدمة وإعادة تشغيل المتصفح إذا تغيرت قيم السجل أو ملف التعريف.
• لا تزال الأصوات السحابية متاحة بعد التعطيل: تأكد من ضبط EnableCloudVoices على false وأن السياسة تظهر كمُدارة في chrome://policy أو edge://policy.

الدعم ذو الأولوية: يتم تضمين معلومات الاتصال بالدعم ذي الأولوية في حزمة الإعداد الخاصة بمؤسستك التعليمية.