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 alasan perubahan tersebut 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 <script> tag dan tempatkan dalam file JS eksternal.

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

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

  • Apakah ekstensi Anda menyuntikkan 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 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 bagian "content_security_policy" dari manifes Anda.

Ringkasan perubahan API

Manifes versi 2 memperkenalkan beberapa perubahan pada API tindakan browser dan tindakan halaman, serta mengganti 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. Properti 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 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 tunggal page_action dan chrome.pageAction.

  • Di bagian properti page_actions lama, terdapat properti icons, name, dan popup. Properti 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 latar belakang.
  • Properti chrome.self telah dihapus, gunakan chrome.extension.
  • Properti Port.tab telah diganti dengan Port.sender.
  • chrome.extension.getTabContentses() dan chrome.extension.getExtensionTabs() API 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 perubahan ini berasal dari penerapan Kebijakan Keamanan Konten oleh Chrome; Anda harus membaca lebih lanjut kebijakan ini untuk memahami implikasinya.

Skrip dan pengendali peristiwa inline tidak diizinkan

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

<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">

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

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

Ini adalah cara yang jauh lebih bersih untuk memisahkan perilaku ekstensi Anda 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 disuntikkan 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"
  ],
...
}

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 kalanya 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 dengan ekstensi Anda.

  2. Anda dapat melonggarkan CSP secara terbatas dengan mengizinkan asal HTTPS di bagian "content_security_policy" dari manifes Anda. Untuk menyertakan library seperti Google Analytics, inilah pendekatan yang harus 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 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 umum digunakan, seperti Google Maps dan library pembuatan template tertentu, diketahui menggunakan beberapa teknik ini.

Chrome menyediakan sandbox untuk halaman yang akan dijalankan di asalnya sendiri, yang ditolak aksesnya ke chrome.* API. 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 sandbox.

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

Bacaan lebih lanjut

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