Halaman ini diterjemahkan oleh Cloud Translation API.

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 yang luas: perubahan API dan Perubahan keamanan.

Dokumen ini menyediakan checklist untuk memigrasikan ekstensi Chrome dari manifes versi 1 ke versi 2, diikuti dengan ringkasan yang lebih mendetail tentang arti perubahan ini dan alasan perubahan tersebut dibuat.

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?
Mengganti dengan chrome.extension.
Apakah Anda menggunakan properti Port.tab?
Mengganti dengan Port.sender.
Apakah Anda menggunakan API chrome.extension.getTabContentses() atau chrome.extension.getExtensionTabs()?
Mengganti 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 sebaris di laman 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 ekstensi tersebut dari kode HTML, pindahkan ke file JS eksternal, dan 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, jika perlu, Kebijakan Keamanan Konten yang 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 mengurai kode JSON menjadi sebuah objek.
Menggunakan library yang mendukung 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 memaketkannya di ekstensi Anda, lalu memuatnya dari paket lokal.
Daftar domain HTTPS yang menyalurkan resource di bagian "content_security_policy" ke dalam daftar yang diizinkan di manifes Anda.

Ringkasan perubahan API

Manifes versi 2 memperkenalkan beberapa perubahan pada API tindakan browser dan tindakan halaman, serta mengganti 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 tunggalnya, browser_action dan chrome.browserAction.
Di bagian properti browser_actions lama, terdapat 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 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 pasangan tunggalnya, page_action dan chrome.pageAction.
Di bagian properti page_actions lama, terdapat properti icons, name, dan popup. Parameter 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 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() 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 tersebut berasal dari adopsi Kebijakan Keamanan Konten Chrome; Anda harus membaca kebijakan ini lebih lanjut 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, anggaplah 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 rujuk konten tersebut dengan atribut src='path_to_file.js'.

Demikian pula, pengendali peristiwa inline, yang merupakan fitur kemudahan dan kemunculan umum yang digunakan oleh banyak developer Web, tidak akan dijalankan. Misalnya, pertimbangkan kasus umum seperti:

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

Fitur ini tidak akan berfungsi di ekstensi manifes V2. Hapus pengendali peristiwa inline, tempatkan dalam file JS eksternal Anda, lalu gunakan addEventListener() untuk mendaftarkan pengendali peristiwa untuknya. Misalnya, di 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 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"
  ],
...
}

Menyematkan konten eksternal: Kebijakan Keamanan Konten hanya mengizinkan skrip dan objek lokal dimuat dari paket Anda, sehingga penyerang eksternal tidak akan 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:

Download library yang relevan secara lokal (seperti jQuery) dan kemas dengan ekstensi Anda.
Anda dapat melonggarkan CSP secara terbatas dengan mengizinkan asal HTTPS di bagian "content_security_policy" manifes Anda. Untuk menyertakan library seperti Google Analytics, berikut 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 manifes v2 baru adalah ekstensi tidak lagi dapat 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 template tertentu, menggunakan beberapa teknik ini.

Chrome menyediakan sandbox agar halaman dapat dijalankan dalam asalnya sendiri, yang aksesnya ditolak ke Chrome.* API. Untuk menggunakan eval() dan sejenisnya berdasarkan Kebijakan Keamanan Konten yang baru:

Buat entri sandbox di file manifes Anda.
Di entri sandbox, cantumkan halaman yang ingin Anda jalankan di sandbox.
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 dalam manifes versi 2 didesain untuk memandu developer mem-build ekstensi dan aplikasi yang lebih aman dan didesain secara tangguh. Untuk melihat daftar lengkap perubahan dari manifes versi 1 ke versi 2, lihat dokumentasi file manifes. Untuk mengetahui informasi lebih lanjut tentang penggunaan sandbox untuk mengisolasi kode yang tidak aman, baca artikel sandboxing eval. Anda dapat mempelajari lebih lanjut Kebijakan Keamanan Konten dengan mengunjungi tutorial terkait ekstensi kami dan pengantar yang bagus tentang HTML5Rocks.