تم إيقاف الإصدار 1 من ملف البيان نهائيًا في الإصدار 18 من Chrome، وسيتم إيقافه نهائيًا وفقًا لجدول إيقاف الإصدار 1 من ملف البيان نهائيًا. تندرج التغييرات من الإصدار 1 إلى الإصدار 2 ضمن مجموعتَين عريقتَين: تغييرات واجهة برمجة التطبيقات وتغييرات الأمان.
يوفّر هذا المستند قوائم تحقّق لنقل بيانات إضافات Chrome من الإصدار 1 من ملف البيان إلى الإصدار 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>وضعه في ملف JavaScript خارجي.هل تستخدِم معالجات أحداث مضمّنة (مثل onclick وما إلى ذلك)؟
أزِلها من رمز HTML، وانقلها إلى ملف JS خارجي واستخدِم
addEventListener()بدلاً من ذلك.هل تُدخل الإضافة نصوصًا برمجية للمحتوى في صفحات الويب التي تحتاج إلى الوصول إلى الموارد (مثل الصور والنصوص البرمجية) المضمّنة في حِزمة الإضافة؟
حدِّد السمة web_accessible_resources وأدرِج الموارد (واختياريًا سياسة أمان محتوى منفصلة لهذه الموارد).
هل تضمّن إضافتك صفحات ويب خارجية؟
حدِّد سمة sandbox.
هل يستخدم الرمز البرمجي أو المكتبة
eval()أوFunction()الجديد أوinnerHTMLأوsetTimeout()أو يمرّر سلاسل رموز JavaScript التي يتم تقييمها ديناميكيًا؟استخدِم
JSON.parse()إذا كنت تُحلِّل رمز JSON إلى عنصر.استخدِم مكتبة متوافقة مع سياسة CSP، مثل AngularJS.
أنشئ إدخالًا في مساحة وضع الحماية في البيان وشغِّل الرمز المتأثّر في مساحة وضع الحماية باستخدام
postMessage()للتواصل مع الصفحة في مساحة وضع الحماية.هل يتم تحميل رمز خارجي، مثل jQuery أو "إحصاءات Google"؟
ننصحك بتنزيل المكتبة وتعبئتها في الإضافة، ثم تحميلها من الحزمة المحلية.
أضِف نطاق HTTPS الذي يعرض المورد إلى القائمة المسموح بها في جزء "content_security_policy" منملف البيان.
ملخّص التغييرات في واجهة برمجة التطبيقات
يقدّم الإصدار 2 من البيان بعض التغييرات على واجهات برمجة التطبيقات الخاصة بإجراءات المتصفّح وإجراءات الصفحة، ويستبدل بعض واجهات برمجة التطبيقات القديمة بأخرى أحدث.
تغييرات على إجراءات المتصفّح
تُجري واجهة برمجة التطبيقات Browser actions API بعض التغييرات على الأسماء:
- تم استبدال السمتَين
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" } ).
ملخّص التغييرات في الأمان
هناك عدد من التغييرات المتعلّقة بالأمان تصاحب الانتقال من الإصدار 1 من ملف البيان إلى الإصدار 2. تعود العديد من هذه التغييرات إلى اعتماد Chrome لسياسة أمان المحتوى، ويجب قراءة المزيد من المعلومات عن هذه السياسة لفهم آثارها.
عدم السماح بالنصوص البرمجية المضمّنة ومعالجات الأحداث
بسبب استخدام سياسة أمان المحتوى، لم يعُد بإمكانك استخدام علامات <script> المضمّنة
في محتوى HTML. يجب نقل هذه الملفات إلى ملفات JavaScript خارجية. بالإضافة إلى ذلك، لا تتوفّر أيضًا معالجات الأحداث المضمّنة. على سبيل المثال، لنفترض أنّ لديك الرمز التالي في الإضافة:
<html>
<head>
<script>
function myFunc() { ... }
</script>
</head>
</html>
سيؤدي هذا الرمز إلى حدوث خطأ أثناء التشغيل. لحلّ هذه المشكلة، عليك نقل محتوى علامة <script> إلى ملفات خارجية
والإشارة إليها باستخدام سمة src='path_to_file.js'.
وبالمثل، لن يتم تنفيذ معالجات الأحداث المضمّنة، وهي ميزة شائعة وملائمة يستخدمها العديد من مطوّري الويب. على سبيل المثال، ننصحك بالتفكير في الحالات الشائعة، مثل:
<body onload="initialize()">
<button onclick="handleClick()" id="button1">
ولن تعمل هذه العناصر في الإضافات المستندة إلى الإصدار 2 من ملف البيان. أزِل معالجات الأحداث المضمّنة، واضبطها في
ملف 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". وهناك طريقتان لذلك:
- نزِّل المكتبة ذات الصلة على الجهاز (مثل jQuery) وحِزمها مع الإضافة.
يمكنك تخفيف سياسة CSP بطريقة محدودة من خلال إدراج مصادر 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() وما شابهه بموجب "سياسة أمان المحتوى" الجديدة:
- أنشئ إدخالًا في مساحة المحاكاة في ملف البيان.
- في إدخال مساحة وضع الحماية، أدرِج الصفحات التي تريد عرضها في مساحة وضع الحماية.
- استخدِم عملية تمرير الرسائل عبر
postMessage()للتواصل مع الصفحة في وضع الحماية.
لمزيد من التفاصيل حول كيفية إجراء ذلك، يُرجى الاطّلاع على مستندات تقييم وضع الحماية.
مراجع إضافية
تم تصميم التغييرات في الإصدار 2 من البيان لإرشاد المطوّرين إلى إنشاء إضافات وتطبيقات أكثر أمانًا و مصمّمة بشكلٍ متين. للاطّلاع على قائمة كاملة بالتغييرات من الإصدار 1 إلى الإصدار 2 من البيان، اطّلِع على مستندات ملف البيان. لمزيد من المعلومات حول استخدام وضع الحماية لعزل الرمز البرمجي غير الآمن، يُرجى قراءة مقالة تقييم وضع الحماية. يمكنك الاطّلاع على مزيد من المعلومات حول سياسة أمان المحتوى من خلال الانتقال إلى الدليل التعليمي المتعلق بالإضافات ومقدمة جيدة حول HTML5Rocks.