Tutorial: Bermigrasi ke Manifes V2

Manifes versi 1 tidak digunakan lagi di Chrome 18, dan dukungan akan dihentikan secara bertahap sesuai dengan jadwal dukungan manifes versi 1. Perubahan dari versi 1 ke versi 2 termasuk dalam dua kategori 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 mendetail tentang arti perubahan ini dan alasannya dilakukan.

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 halaman peristiwa

Checklist perubahan keamanan

  • Apakah Anda menggunakan blok skrip inline di halaman HTML?

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

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

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

  • Apakah ekstensi Anda memasukkan skrip konten ke halaman Web yang perlu mengakses resource (seperti gambar dan skrip) yang terdapat 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() baru, innerHTML, setTimeout(), atau meneruskan string kode JS yang dievaluasi secara dinamis?

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

  • Gunakan library yang kompatibel dengan CSP, misalnya, AngularJS.

  • Buat entri sandbox dalam manifes Anda dan jalankan kode yang terpengaruh di sandbox, menggunakan postMessage() untuk berkomunikasi dengan halaman dengan 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.

  • Tambahkan domain HTTPS yang menayangkan resource di bagian "content_security_policy" dalam manifes Anda.

Ringkasan perubahan API

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

Perubahan pada tindakan browser

API tindakan browser memperkenalkan beberapa perubahan penamaan:

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

  • Di bagian properti browser_actions lama, terdapat properti icons, name, dan popup. Keduanya 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 mewakili UI untuk tindakan browser (dan sekarang harus berupa string, tidak boleh berupa objek)

Perubahan pada tindakan halaman

Serupa dengan perubahan untuk tindakan browser, API tindakan halaman juga telah berubah:

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

  • Di properti page_actions lama, terdapat 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 sekarang harus berupa string, tidak boleh berupa objek)

API yang dihapus dan diubah

Beberapa API ekstensi telah dihapus dan diganti dengan API baru:

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

Ringkasan perubahan keamanan

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

Skrip inline dan pengendali peristiwa tidak diizinkan

Karena penggunaan Kebijakan Keamanan Konten, Anda tidak dapat lagi 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 di ekstensi:

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

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

Demikian pula, pengendali peristiwa inline, yang merupakan fitur umum dan praktis yang digunakan oleh banyak developer Web, tidak akan dieksekusi. Misalnya, pertimbangkan instance umum seperti:

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

Ekstensi ini tidak akan berfungsi di ekstensi manifes V2. Hapus pengendali peristiwa inline, tempatkan di file JS eksternal, lalu gunakan addEventListener() untuk mendaftarkan pengendali peristiwa untuknya. Misalnya, dalam kode JS, gunakan:

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

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

Menyematkan konten

Ada beberapa skenario saat ekstensi Anda mungkin 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 skrip konten yang dimasukkan ke halaman web, Anda harus menggunakan properti web_accessible_resources untuk mengizinkan resource ini sehingga halaman Web eksternal dapat menggunakannya:

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

Menyertakan 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, adakalanya 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 paketkan dengan ekstensi Anda.

  2. Anda dapat melonggarkan CSP secara terbatas dengan mengizinkan origin HTTPS di bagian "content_security_policy" dalam manifes Anda. Untuk menyertakan library seperti Google Analytics, ini adalah pendekatan yang harus dilakukan:

    {
  ...,
  "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 manifest v2 baru adalah ekstensi tidak dapat lagi menggunakan teknik evaluasi skrip dinamis seperti eval() atau Function() baru, atau meneruskan string kode JS ke fungsi yang akan menyebabkan eval() digunakan, seperti setTimeout(). Selain itu, library JavaScript tertentu yang biasa digunakan, seperti Google Maps dan library template tertentu, diketahui menggunakan beberapa teknik ini.

Chrome menyediakan sandbox untuk halaman agar dapat berjalan di origin-nya sendiri, yang ditolak aksesnya ke Chrome.* rendah. Untuk menggunakan eval() dan sejenisnya berdasarkan Kebijakan Keamanan Konten baru:

  1. Buat entri sandbox di file manifes Anda.
  2. Di entri sandbox, cantumkan halaman yang ingin Anda jalankan di sandbox.
  3. Gunakan penerusan pesan melalui postMessage() untuk berkomunikasi dengan halaman dengan sandbox.

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

Bacaan lebih lanjut

Perubahan dalam manifes versi 2 dirancang untuk memandu developer dalam membuat ekstensi dan aplikasi yang lebih aman dan memiliki arsitektur yang andal. Untuk melihat daftar lengkap perubahan dari manifes versi 1 ke versi 2, lihat dokumentasi file manifes. Untuk mengetahui informasi selengkapnya tentang penggunaan sandbox untuk mengisolasi kode yang tidak aman, baca artikel sandboxing eval. Anda dapat mempelajari lebih lanjut Kebijakan Keamanan Konten dengan membuka tutorial terkait ekstensi kami dan pengantar yang bagus di HTML5Rocks.