Tutorial: Bermigrasi ke Manifes V2

Manifes versi 1 tidak digunakan lagi di Chrome 18, dan dukungan akan dihentikan sesuai dengan jadwal dukungan manifes versi 1. Perubahan dari versi 1 ke versi 2 berada di bawah dua kategori yang luas: Perubahan API dan Perubahan keamanan.

Dokumen ini menyediakan checklist untuk memigrasikan ekstensi Chrome Anda dari manifes versi 1 ke versi 2, diikuti dengan ringkasan yang lebih terperinci tentang arti perubahan ini dan alasannya.

Checklist perubahan API

  • Apakah Anda menggunakan properti browser_actions atau chrome.browserActions API?

  • Ganti browser_actions dengan properti browser_action tunggal.

  • Ganti chrome.browserActions dengan chrome.browserAction.

  • Ganti properti icons dengan default_icon.

  • Ganti properti name dengan default_title.

  • Ganti properti popup dengan default_popup (dan sekarang harus berupa string).

  • Apakah Anda menggunakan properti page_actions atau chrome.pageActions API?

  • Ganti page_actions dengan page_action.

  • Ganti chrome.pageActions dengan chrome.pageAction.

  • Ganti properti icons dengan default_icon.

  • Ganti properti name dengan default_title.

  • Ganti properti popup dengan default_popup (dan sekarang harus berupa string).

  • Apakah Anda menggunakan properti chrome.self?

  • Ganti dengan chrome.extension.

  • Apakah Anda menggunakan properti Port.tab?

  • Ganti dengan Port.sender.

  • Apakah Anda menggunakan chrome.extension.getTabContentses() atau chrome.extension.getExtensionTabs() API?

  • Ganti dengan chrome.extension.getViews( { "type" : "tab" } ).

  • Apakah ekstensi Anda menggunakan halaman latar belakang?

  • Ganti properti background_page dengan properti background.

  • Tambahkan properti scripts atau page yang berisi kode untuk halaman.

  • Tambahkan properti persistent dan tetapkan ke false untuk mengonversi halaman latar belakang menjadi peristiwa halaman

Checklist perubahan keamanan

  • Apakah Anda menggunakan blok skrip sebaris di halaman HTML?

  • Hapus kode JS yang ada dalam tag <script> dan tempatkan dalam file JS eksternal.

  • Apakah Anda menggunakan pengendali peristiwa inline (seperti onclick, dll.)?

  • Hapus semuanya dari kode HTML, pindahkan ke file JS eksternal, dan gunakan addEventListener() sebagai gantinya.

  • Apakah ekstensi Anda memasukkan skrip konten ke laman Web yang perlu mengakses sumber daya (seperti gambar dan skrip) yang ada dalam paket ekstensi?

  • Tentukan properti web_accessible_resources dan cantumkan resource (dan secara opsional Kebijakan Keamanan Konten terpisah untuk resource tersebut).

  • Apakah ekstensi Anda menyematkan halaman Web eksternal?

  • Tentukan properti sandbox.

  • Apakah kode atau library Anda menggunakan eval(), Function(), innerHTML, setTimeout() yang baru, atau jika tidak, meneruskan string kode JS yang dievaluasi secara dinamis?

  • Gunakan JSON.parse() jika Anda mengurai kode JSON menjadi sebuah objek.

  • Gunakan library yang cocok untuk CSP, misalnya, AngularJS.

  • Buat entri sandbox di manifes Anda dan jalankan kode yang terpengaruh di sandbox, menggunakan postMessage() untuk berkomunikasi dengan halaman dalam sandbox.

  • Apakah Anda memuat kode eksternal, seperti jQuery atau Google Analytics?

  • Pertimbangkan untuk mendownload library dan mengemasnya dalam ekstensi Anda, lalu memuatnya dari paket lokal.

  • Izinkan domain HTTPS yang menayangkan resource di "content_security_policy" bagian dari manifes.

Ringkasan perubahan API

Manifes versi 2 memperkenalkan beberapa perubahan pada API tindakan halaman dan tindakan browser, serta menggantikan beberapa API lama dengan yang lebih baru.

Perubahan pada tindakan browser

API tindakan browser memperkenalkan beberapa perubahan penamaan:

  • Properti browser_actions dan chrome.browserActions telah diganti dengan pasangan tunggal browser_action dan chrome.browserAction.

  • Di bawah properti browser_actions lama, ada properti icons, name, dan popup. Hal ini telah diganti dengan:

  • default_icon untuk ikon badge tindakan browser

  • default_name untuk teks yang muncul di tooltip saat Anda mengarahkan kursor ke badge

  • default_popup untuk halaman HTML yang merepresentasikan UI untuk tindakan browser (dan sekarang harus berupa string, tidak boleh berupa objek)

Perubahan pada tindakan halaman

Serupa dengan perubahan pada tindakan browser, API tindakan halaman juga berubah:

  • Properti page_actions dan chrome.pageActions telah diganti dengan bentuk tunggalnya kemiripan dengan page_action dan chrome.pageAction.

  • Di bawah properti page_actions lama, ada properti icons, name, dan popup. Ini telah diganti dengan:

  • default_icon untuk ikon badge tindakan halaman

  • default_name untuk teks yang muncul di tooltip saat Anda mengarahkan kursor ke badge

  • default_popup untuk halaman HTML yang mewakili UI untuk tindakan halaman (dan ini sekarang harus string, tidak boleh berupa objek)

API yang dihapus dan diubah

Beberapa API ekstensi telah dihapus dan diganti dengan API ekstensi yang baru:

  • Properti background_page telah diganti dengan latar belakang.
  • Properti chrome.self telah dihapus, gunakan chrome.extension.
  • Properti Port.tab telah diganti dengan Port.sender.
  • API chrome.extension.getTabContentses() dan chrome.extension.getExtensionTabs() memiliki telah diganti dengan chrome.extension.getViews( { "type" : "tab" } ).

Ringkasan perubahan keamanan

Ada sejumlah perubahan terkait keamanan yang menyertai peralihan dari manifes versi 1 ke versi 2. Banyak dari perubahan ini berasal dari adopsi Kebijakan Keamanan Konten oleh Chrome; Anda harus membaca lebih lanjut tentang kebijakan ini untuk memahami implikasinya.

Skrip inline dan pengendali peristiwa tidak diizinkan

Karena penggunaan Kebijakan Keamanan Konten, Anda tidak lagi dapat menggunakan tag <script> yang inline dengan konten HTML. File ini harus dipindahkan ke file JS eksternal. Selain itu, pengendali peristiwa inline juga tidak didukung. Misalnya, Anda memiliki kode berikut dalam ekstensi:

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

Kode ini akan menyebabkan error pada runtime. Untuk memperbaikinya, pindahkan konten tag <script> ke file eksternal dan mereferensikannya dengan atribut src='path_to_file.js'.

Demikian pula, pengendali peristiwa inline, yang merupakan kemunculan dan fitur praktis yang umum digunakan oleh banyak Pengembang web, tidak akan mengeksekusi. Misalnya, pertimbangkan contoh umum seperti:

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

Ini tidak akan berfungsi di ekstensi Manifes V2. Menghapus pengendali peristiwa inline, menempatkannya di file JS eksternal dan menggunakan addEventListener() untuk mendaftarkan pengendali peristiwa untuk file tersebut. Sebagai misalnya, dalam kode JS Anda, gunakan:

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

Ini adalah cara yang jauh lebih rapi untuk memisahkan perilaku ekstensi Anda dari markup antarmuka penggunanya.

Menyematkan konten

Ada beberapa skenario yang memungkinkan ekstensi Anda menyematkan konten yang dapat digunakan secara eksternal atau berasal dari sumber eksternal.

Konten ekstensi di halaman web: Jika ekstensi Anda menyematkan resource (seperti gambar, skrip, gaya CSS, dll.) yang digunakan dalam konten skrip yang dimasukkan ke halaman web, Anda harus menggunakan properti web_accessible_resources untuk menambahkan referensi ini ke daftar yang diizinkan agar halaman Web eksternal dapat menggunakannya:

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

Menyematkan konten eksternal: Kebijakan Keamanan Konten hanya mengizinkan skrip dan objek lokal dimuat dari paket Anda, yang mencegah penyerang eksternal memasukkan kode yang tidak dikenal ke ekstensi Anda. Namun, ada saat Anda ingin memuat resource yang ditayangkan secara eksternal, seperti kode jQuery atau Google Analytics. Ada 2 cara untuk melakukannya:

  1. Download library yang relevan secara lokal (seperti jQuery) dan kemas bersama ekstensi Anda.

  2. Anda bisa melonggarkan CSP secara terbatas dengan memasukkan sumber HTTPS ke daftar yang diizinkan &quot;content_security_policy&quot; dari manifes Anda. Untuk menyertakan pustaka seperti Google Analytics, inilah pendekatan yang diambil:

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

Menggunakan evaluasi skrip dinamis

Mungkin salah satu perubahan terbesar dalam skema manifes v2 yang baru adalah ekstensi tidak dapat lagi gunakan teknik evaluasi skrip dinamis seperti eval() atau Function() baru, atau teruskan string JS kode ke fungsi yang akan menyebabkan eval() digunakan, seperti setTimeout(). Selain itu, beberapa library JavaScript yang umum digunakan, seperti Google Maps dan library template tertentu, dikenal menggunakan beberapa teknik ini.

Chrome menyediakan sandbox untuk halaman agar berjalan di asalnya sendiri, yang tidak dapat mengakses Chrome.* atau salah satu dari JSON atau XML API. Untuk menggunakan eval() dan sejenisnya berdasarkan Kebijakan Keamanan Konten yang baru:

  1. Buat entri sandbox di file manifes Anda.
  2. Dalam entri {i>sandbox<i}, cantumkan halaman yang ingin Anda jalankan di {i>sandbox<i}.
  3. Gunakan pesan yang diteruskan melalui postMessage() untuk berkomunikasi dengan halaman dalam sandbox.

Untuk detail selengkapnya tentang cara melakukannya, lihat dokumentasi Sandboxing Eval.

Bacaan lebih lanjut

Perubahan di manifes versi 2 dirancang untuk memandu pengembang agar membangun solusi yang lebih aman dan ekstensi dan aplikasi dengan arsitektur yang kuat. Untuk melihat daftar lengkap perubahan dari manifes versi 1 ke versi 2, lihat dokumentasi file manifes. Untuk informasi lebih lanjut tentang penggunaan {i>sandbox<i} untuk mengisolasi kode yang tidak aman, baca artikel sandboxing eval. Anda dapat mempelajari lebih lanjut Kebijakan Keamanan dengan mengunjungi tutorial kami yang terkait ekstensi dan pengantar yang bagus tentang HTML5Rocks.