البرنامج التعليمي: الانتقال إلى إصدار Manifest V2

تمّ إيقاف إصدار Manifest V1 نهائيًا في Chrome 18، وسيتم إيقاف الدعم تدريجيًا وفقًا للـ جدول الزمني لدعم إصدار Manifest V1. تندرج التغييرات من الإصدار 1 إلى الإصدار 2 ضمن فئتَين عريضتَين: تغييرات واجهة برمجة التطبيقات والتغييرات الأمنية.

تقدّم هذه المستندات قوائم تحقّق لنقل بيانات إضافات Chrome من إصدار Manifest V1 إلى الإصدار 2، يليها ملخّصات أكثر تفصيلاً لما تعنيه هذه التغييرات وسبب إجرائها.

قائمة التحقّق من تغييرات واجهة برمجة التطبيقات

  • هل تستخدم السمة browser_actions أو واجهة برمجة التطبيقات chrome.browserActions؟

  • استبدِل browser_actions بالسمة المفردة browser_action.

  • استبدِل chrome.browserActions بـ chrome.browserAction.

  • استبدِل السمة icons بـ default_icon.

  • استبدِل السمة name بـ default_title.

  • استبدِل السمة popup بـ default_popup (ويجب أن تكون الآن سلسلة).

  • هل تستخدم السمة page_actions أو واجهة برمجة التطبيقات chrome.pageActions؟

  • استبدِل page_actions بـ page_action.

  • استبدِل chrome.pageActions بـ chrome.pageAction.

  • استبدِل السمة icons بـ default_icon.

  • استبدِل السمة name بـ default_title.

  • استبدِل السمة popup بـ default_popup (ويجب أن تكون الآن سلسلة).

  • هل تستخدم السمة chrome.self؟

  • استبدِلها بـ chrome.extension.

  • هل تستخدم السمة Port.tab؟

  • استبدِلها بـ Port.sender.

  • هل تستخدم واجهتَي برمجة التطبيقات chrome.extension.getTabContentses() أو chrome.extension.getExtensionTabs()؟

  • استبدِلهما بـ chrome.extension.getViews( { "type" : "tab" } ).

  • هل تستخدم إضافتك صفحة في الخلفية؟

  • استبدِل السمة background_page بالسمة background.

  • أضِف السمة scripts أو page التي تحتوي على الرمز البرمجي للصفحة.

  • أضِف السمة persistent واضبطها على false لتحويل صفحة الخلفية إلى صفحة أحداث

قائمة التحقّق من التغييرات الأمنية

  • هل تستخدم كتل النصوص البرمجية المضمّنة في صفحات HTML؟

  • أزِل رمز JavaScript المضمّن ضمن علامتَي <script> وضعها في ملف JS خارجي.

  • هل تستخدم معالجات الأحداث المضمّنة (مثل onclick وما إلى ذلك)؟

  • أزِلها من رمز HTML وانقلها إلى ملف JS خارجي واستخدِم addEventListener() بدلاً من ذلك.

  • هل تُدخِل إضافتك نصوصًا برمجية للمحتوى في صفحات الويب التي تحتاج إلى الوصول إلى موارد (مثل الصور والنصوص البرمجية) مضمّنة في حزمة الإضافة؟

  • حدِّد السمة web_accessible_resources وأدرِج الموارد (ويمكنك اختياريًا تحديد "سياسة أمان محتوى" منفصلة لهذه الموارد).

  • هل تُضمِّن إضافتك صفحات ويب خارجية؟

  • حدِّد الس0}sandbox السمة.

  • هل يستخدم الرمز البرمجي أو المكتبة eval() أو Function() أو innerHTML أو setTimeout() أو يمرِّر بطريقة أخرى سلاسل من رمز JS يتم تقييمه ديناميكيًا؟

  • استخدِم JSON.parse() إذا كنت تحلّل رمز JSON إلى عنصر.

  • استخدِم مكتبة متوافقة مع "سياسة أمان المحتوى"، مثل AngularJS.

  • أنشِئ إدخال وضع الحماية في ملف البيان وشغِّل الرمز البرمجي المتأثر في وضع الحماية، باستخدام postMessage() للتواصل مع الصفحة التي تم وضعها في وضع الحماية.

  • هل تحمِّل رمزًا خارجيًا، مثل jQuery أو "إحصاءات Google"؟

  • نزِّل المكتبة وضَعها في حزمة إضافتك، ثم حمِّلها من الحزمة المحلية.

  • أضِف النطاق HTTPS الذي يعرض المورد إلى القائمة المسموح بها في جزء "content_security_policy" من ملف البيان.

ملخّص تغييرات واجهة برمجة التطبيقات

يُدخِل إصدار Manifest V2 بعض التغييرات على واجهات برمجة التطبيقات لإجراءات المتصفّح وإجراءات الصفحة، ويستبدِل بعض واجهات برمجة التطبيقات القديمة بواجهات أحدث.

التغييرات في إجراءات المتصفّح

تُدخِل واجهة برمجة التطبيقات لإجراءات المتصفّح بعض التغييرات في التسمية:

  • تم استبدال السمتَين browser_actions وchrome.browserActions بالسمتَين المفردتَين browser_action وchrome.browserAction.

  • ضمن السمة القديمة browser_actions، كانت هناك سمات icons وname وpopup. تم استبدالها بما يلي:

  • default_icon لرمز شارة إجراء المتصفّح

  • default_name للنص الذي يظهر في تلميح الأداة عند تمرير مؤشر الماوس فوق الشارة

  • default_popup لصفحة HTML التي تمثّل واجهة مستخدم إجراء المتصفّح (ويجب أن تكون الآن سلسلة، ولا يمكن أن تكون كائنًا)

التغييرات في إجراءات الصفحة

على غرار التغييرات في إجراءات المتصفّح، تغيّرت أيضًا واجهة برمجة التطبيقات لإجراءات الصفحة:

  • تم استبدال السمتَين page_actions وchrome.pageActions بالسمتَين المفردتَين page_action وchrome.pageAction.

  • ضمن السمة القديمة page_actions، كانت هناك سمات icons وname وpopup. تم استبدالها بما يلي:

  • default_icon لرمز شارة إجراء الصفحة

  • default_name للنص الذي يظهر في تلميح الأداة عند تمرير مؤشر الماوس فوق الشارة

  • default_popup لصفحة HTML التي تمثّل واجهة مستخدم إجراء الصفحة (ويجب أن تكون الآن سلسلة، ولا يمكن أن تكون كائنًا)

واجهات برمجة التطبيقات التي تمت إزالتها وتغييرها

تمت إزالة بعض واجهات برمجة التطبيقات للإضافات واستبدالها بواجهات جديدة:

  • تم استبدال السمة background_page بالسمة background.
  • تمت إزالة السمة chrome.self، استخدِم chrome.extension.
  • تم استبدال السمة Port.tab بالسمة Port.sender.
  • تم استبدال واجهتَي برمجة التطبيقات chrome.extension.getTabContentses() وchrome.extension.getExtensionTabs() بواجهة chrome.extension.getViews( { "type" : "tab" } ).

ملخّص التغييرات الأمنية

هناك عدد من التغييرات المتعلّقة بالأمان التي تصاحب الانتقال من إصدار Manifest V1 إلى الإصدار 2. ينتج العديد من هذه التغييرات عن اعتماد Chrome لـ سياسة أمان المحتوى؛ ننصحك بالاطّلاع على مزيد من المعلومات حول هذه السياسة لفهم آثارها.

عدم السماح بالنصوص البرمجية المضمّنة ومعالجات الأحداث

بسبب استخدام سياسة أمان المحتوى، لم يعُد بإمكانك استخدام علامتَي <script> المضمّنتَين في محتوى HTML. يجب نقلهما إلى ملفات JS خارجية. بالإضافة إلى ذلك، لا يتم أيضًا دعم معالجات الأحداث المضمّنة. على سبيل المثال، لنفترض أنّ لديك الرمز البرمجي التالي في إضافتك:

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

سيؤدي هذا الرمز البرمجي إلى حدوث خطأ في وقت التشغيل. لحلّ هذه المشكلة، انقل محتويات علامتَي <script> إلى ملفات خارجية وأشِر إليها باستخدام السمة src='path_to_file.js'.

وبالمثل، لن يتم تنفيذ معالجات الأحداث المضمّنة، وهي ميزة شائعة ومريحة يستخدمها العديد من مطوّري الويب. على سبيل المثال، لنفترض الحالات الشائعة التالية:

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

لن تعمل هذه الحالات في إضافات Manifest V2. أزِل معالجات الأحداث المضمّنة وضَعها في ملف JS خارجي واستخدِم addEventListener() لتسجيل معالجات الأحداث لها بدلاً من ذلك. على سبيل المثال، في رمز JS، استخدِم:

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

هذه طريقة أكثر وضوحًا لفصل سلوك إضافتك عن ترميز واجهة المستخدم.

تضمين المحتوى

هناك بعض السيناريوهات التي قد تُضمِّن فيها إضافتك محتوى يمكن استخدامه خارجيًا أو يأتي من مصدر خارجي.

محتوى الإضافة في صفحات الويب: إذا كانت إضافتك تُضمِّن موارد (مثل الصور والنصوص البرمجية وأنماط CSS وما إلى ذلك) مستخدَمة في نصوص برمجية للمحتوى يتم إدخالها في صفحات الويب، عليك استخدام السمة web_accessible_resources لإضافة هذه الموارد إلى القائمة المسموح بها حتى تتمكّن صفحات الويب الخارجية من استخدامها:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

تضمين محتوى خارجي: لا تسمح "سياسة أمان المحتوى" إلا بتحميل النصوص البرمجية والكائنات المحلية من حزمتك، ما يمنع المهاجمين الخارجيين من إدخال رمز غير معروف إلى إضافتك. ومع ذلك، هناك أوقات تريد فيها تحميل موارد يتم عرضها خارجيًا، مثل jQuery أو رمز "إحصاءات Google". هناك طريقتان لذلك:

  1. نزِّل المكتبة ذات الصلة محليًا (مثل jQuery) وضَعها في حزمة إضافتك.

  2. يمكنك تخفيف "سياسة أمان المحتوى" بطريقة محدودة من خلال إضافة مصادر HTTPS إلى القائمة المسموح بها في قسم "content_security_policy" من ملف البيان. لتضمين مكتبة مثل "إحصاءات Google"، عليك اتّباع هذا النهج:

    {
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}

استخدام التقييم الديناميكي للنصوص البرمجية

ربما يكون أحد أكبر التغييرات في نظام Manifest V2 الجديد هو أنّه لم يعُد بإمكان الإضافات استخدام تقنيات التقييم الديناميكي للنصوص البرمجية، مثل eval() أو Function() الجديدة، أو تمرير سلاسل من رمز JS إلى وظائف ستؤدي إلى استخدام eval()، مثل setTimeout(). بالإضافة إلى ذلك، من المعروف أنّ بعض مكتبات JavaScript الشائعة الاستخدام، مثل "خرائط Google" وبعض مكتبات إنشاء النماذج، تستخدم بعض هذه التقنيات.

يوفّر Chrome وضع حماية للصفحات لتشغيلها في مصدرها الخاص، ويتم رفض الوصول إلى واجهات برمجة التطبيقات chrome.*. في إطار "سياسة أمان المحتوى" الجديدة، لاستخدام `eval()` وما شابه: لاستخدام eval() وما شابه ذلك بموجب "سياسة أمان المحتوى" الجديدة، يجب اتّباع ما يلي:

  1. أنشِئ إدخال وضع الحماية في ملف البيان.
  2. في إدخال وضع الحماية، أدرِج الصفحات التي تريد تشغيلها في وضع الحماية.
  3. استخدِم تمرير الرسائل من خلال postMessage() للتواصل مع الصفحة التي تم وضعها في وضع الحماية.

لمزيد من التفاصيل حول كيفية إجراء ذلك، اطّلِع على مستندات وضع الحماية لـ Eval.

محتوى إضافي للقراءة

تم تصميم التغييرات في إصدار Manifest V2 لتوجيه المطوّرين نحو إنشاء إضافات وتطبيقات أكثر أمانًا ومصمّمة بشكل قوي. للاطّلاع على قائمة كاملة بالتغييرات من إصدار Manifest V1 إلى الإصدار 2، اطّلِع على مستندات ملف البيان. لمزيد من المعلومات حول استخدام وضع الحماية لعزل الرمز البرمجي غير الآمن، اطّلِع على مقالة وضع الحماية لـ Eval. يمكنك الاطّلاع على مزيد من المعلومات حول Content سياسة أمان المحتوى من خلال الانتقال إلى البرنامج التعليمي ذي الصلة بالإضافات ومقدمة جيدة على HTML5Rocks.