chrome.permissions

Deskripsi

Gunakan chrome.permissions API untuk meminta izin opsional yang dideklarasikan pada waktu proses, bukan waktu penginstalan, sehingga pengguna memahami alasan izin diperlukan dan hanya memberikan izin yang diperlukan.

Konsep dan penggunaan

Peringatan izin ada untuk menjelaskan kemampuan yang diberikan oleh API, tetapi beberapa peringatan ini mungkin tidak jelas. Izin API memungkinkan developer menjelaskan peringatan izin dan memperkenalkan fitur baru secara bertahap yang memberi pengguna pengenalan ekstensi yang bebas risiko. Dengan cara ini, pengguna dapat menentukan seberapa banyak akses yang ingin mereka berikan dan fitur mana yang ingin mereka aktifkan.

Misalnya, fungsi inti ekstensi izin opsional menggantikan halaman tab baru. Salah satu fitur adalah menampilkan sasaran pengguna hari ini. Fitur ini hanya memerlukan izin penyimpanan, yang tidak mencakup peringatan. Ekstensi ini memiliki fitur tambahan yang dapat diaktifkan oleh pengguna dengan mengklik tombol berikut:

Tombol ekstensi yang mengaktifkan fitur tambahan.
Tombol ekstensi yang mengaktifkan fitur tambahan.

Menampilkan situs teratas pengguna memerlukan izin topSites, yang memiliki peringatan berikut.

Peringatan aktivasi untuk topSites API.
Peringatan ekstensi untuk topSites API

Mengimplementasikan izin opsional

Langkah 1: Tentukan izin yang diperlukan dan yang bersifat opsional

Ekstensi dapat mendeklarasikan izin wajib dan opsional. Secara umum, Anda harus:

  • Gunakan izin yang diperlukan saat diperlukan untuk fungsi dasar ekstensi Anda.
  • Gunakan izin opsional jika diperlukan untuk fitur opsional di ekstensi Anda.

Keuntungan izin yang diperlukan:

  • Lebih sedikit perintah: Ekstensi dapat meminta pengguna sekali untuk menyetujui semua izin.
  • Pengembangan yang lebih sederhana: Izin yang diperlukan dijamin selalu ada.

Keuntungan izin opsional:

  • Keamanan yang lebih baik: Ekstensi berjalan dengan lebih sedikit izin karena pengguna hanya mengaktifkan izin yang dibutuhkan.
  • Informasi yang lebih baik untuk pengguna: Ekstensi dapat menjelaskan mengapa ekstensi memerlukan izin tertentu saat pengguna mengaktifkan fitur yang relevan.
  • Upgrade yang lebih mudah: Saat mengupgrade ekstensi, Chrome tidak akan menonaktifkannya untuk pengguna jika upgrade akan menambahkan izin opsional, bukannya izin yang diwajibkan.

Langkah 2: Deklarasikan izin opsional dalam manifes

Deklarasikan izin opsional di manifes ekstensi dengan kunci optional_permissions, menggunakan format yang sama dengan kolom izin:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Jika ingin meminta host yang hanya Anda temukan saat runtime, sertakan "https://*/*" dalam kolom optional_host_permissions ekstensi Anda. Hal ini memungkinkan Anda menentukan origin apa pun di "Permissions.origins" selama memiliki origin yang cocok skema baru.

Izin yang tidak dapat ditetapkan sebagai opsional

Sebagian besar izin ekstensi Chrome dapat ditetapkan sebagai opsional, dengan pengecualian berikut.

Izin Deskripsi
"debugger" API chrome.debugger berfungsi sebagai transpor alternatif untuk proses debug jarak jauh Chrome protokol yang sama.
"declarativeNetRequest" Memberikan akses ekstensi ke chrome.declarativeNetRequest API.
"devtools" Mengizinkan ekstensi untuk meluaskan Chrome DevTools fungsionalitasnya.
"geolocation" Mengizinkan ekstensi untuk menggunakan API geolokasi HTML5.
"mdns" Memberi ekstensi akses ke chrome.mdns.
"proxy" Memberikan akses ekstensi ke API chrome.proxy untuk mengelola proxy Chrome setelan.
"tts" Pemutaran API chrome.tts secara sintetis text-to-speech (TTS).
"ttsEngine" API chrome.ttsEngine menerapkan mesin text-to-speech (TTS) menggunakan ekstensi.
"wallpaper" Khusus ChromeOS. Gunakan API chrome.wallpaper untuk mengubah ChromeOS wallpaper.

Lihat Mendeklarasikan Izin untuk informasi lebih lanjut tentang izin dan peringatan mereka.

Langkah 3: Minta izin opsional

Minta izin dari dalam gestur pengguna menggunakan permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome akan memberi tahu pengguna jika menambahkan izin akan menghasilkan pesan peringatan yang berbeda dengan yang telah dilihat dan disetujui pengguna. Misalnya, kode sebelumnya mungkin menghasilkan perintah seperti ini:

Contoh dialog konfirmasi izin.
Contoh perintah konfirmasi izin.

Langkah 4: Periksa izin ekstensi saat ini

Untuk memeriksa apakah ekstensi Anda memiliki izin atau sekumpulan izin tertentu, gunakan permission.contains():

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

Langkah 5: Hapus izin

Sebaiknya hapus izin saat Anda tidak lagi memerlukannya. Setelah izin akses dihapus, memanggil permissions.request() biasanya akan menambahkan izin kembali tanpa meminta konfirmasi pengguna.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

Jenis

Permissions

Properti

  • origin

    string[] opsional

    Daftar izin host, termasuk yang ditentukan dalam kunci optional_permissions atau permissions dalam manifes, dan yang terkait dengan Skrip Konten.

  • izin

    string[] opsional

    Daftar izin bernama (tidak termasuk host atau origin).

Metode

contains()

Janji 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Memeriksa apakah ekstensi memiliki izin yang ditentukan.

Parameter

  • izin

    Izin

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (result: boolean) => void

    • hasil

      boolean

      True jika ekstensi memiliki izin yang ditentukan. Jika origin ditetapkan sebagai izin opsional dan pola pencocokan skrip konten, kueri ini akan menampilkan false kecuali jika kedua izin tersebut diberikan.

Hasil

  • Promise<boolean>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getAll()

Janji 
chrome.permissions.getAll(
  callback?: function,
)

Mendapatkan kumpulan izin ekstensi saat ini.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (permissions: Permissions) => void

    • izin

      Izin

      Izin aktif ekstensi. Perhatikan bahwa properti origins akan berisi origin yang diberikan dari origin yang ditentukan dalam kunci permissions dan optional_permissions dalam manifes dan yang terkait dengan Skrip Konten.

Hasil

  • Promise<Permissions>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

remove()

Janji 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Menghapus akses ke izin yang ditentukan. Jika ada masalah saat menghapus izin, runtime.lastError akan ditetapkan.

Parameter

  • izin

    Izin

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (removed: boolean) => void

    • dihapus

      boolean

      True jika izin dihapus.

Hasil

  • Promise<boolean>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

request()

Janji 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Meminta akses ke izin yang ditentukan, dengan menampilkan perintah kepada pengguna jika diperlukan. Izin ini harus ditentukan di kolom optional_permissions pada manifes atau merupakan izin wajib yang ditahan oleh pengguna. Jalur pada pola origin akan diabaikan. Anda dapat meminta subset izin origin opsional; misalnya, jika Anda menentukan *://*\/* di bagian optional_permissions pada manifes, Anda dapat meminta http://example.com/. Jika ada masalah saat meminta izin, runtime.lastError akan ditetapkan.

Parameter

  • izin

    Izin

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (granted: boolean) => void

    • diberikan

      boolean

      True jika pengguna memberikan izin yang ditentukan.

Hasil

  • Promise<boolean>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

Diaktifkan saat ekstensi memperoleh izin baru.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

Diaktifkan saat akses ke izin telah dihapus dari ekstensi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (permissions: Permissions) => void