chrome.permissions

Deskripsi

Gunakan chrome.permissions API untuk meminta izin opsional yang dideklarasikan saat runtime, 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. Permissions API memungkinkan developer menjelaskan peringatan izin dan memperkenalkan fitur baru secara bertahap, sehingga pengguna dapat mengenal ekstensi tanpa risiko. Dengan demikian, pengguna dapat menentukan jumlah akses yang ingin mereka berikan dan fitur yang ingin diaktifkan.

Misalnya, fungsi inti ekstensi izin opsional mengganti halaman tab baru. Salah satu fitur menampilkan sasaran harian pengguna. Fitur ini hanya memerlukan izin penyimpanan, yang tidak menyertakan peringatan. Ekstensi ini memiliki fitur tambahan, yang dapat diaktifkan 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 ekstensi untuk topSites API.
Peringatan ekstensi untuk topSites API

Menerapkan 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 jika diperlukan untuk fungsi dasar ekstensi Anda.
  • Gunakan izin opsional jika diperlukan untuk fitur opsional di ekstensi Anda.

Kelebihan izin yang diperlukan:

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

Kelebihan izin opsional:

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

Langkah 2: Deklarasikan izin opsional dalam manifes

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

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

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

Izin yang tidak dapat ditentukan sebagai opsional

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

Izin Deskripsi
"debugger" chrome.debugger API berfungsi sebagai transpor alternatif untuk protokol proses debug jarak jauh Chrome.
"declarativeNetRequest" Memberikan akses ekstensi ke chrome.declarativeNetRequest API.
"devtools" Memungkinkan ekstensi memperluas fungsi Chrome DevTools.
"geolocation" Mengizinkan ekstensi menggunakan API geolokasi HTML5.
"mdns" Memberikan akses ekstensi ke chrome.mdns API.
"proxy" Memberikan akses ekstensi ke chrome.proxy API untuk mengelola setelan proxy Chrome.
"tts" chrome.tts API memutar text-to-speech (TTS) sintetis.
"ttsEngine" chrome.ttsEngine API mengimplementasikan mesin text-to-speech (TTS) menggunakan ekstensi.
"wallpaper" Khusus ChromeOS. Gunakan API chrome.wallpaper untuk mengubah wallpaper ChromeOS.

Lihat Mendeklarasikan Izin untuk mengetahui informasi lebih lanjut tentang izin yang tersedia dan peringatannya.

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 meminta pengguna jika menambahkan izin menghasilkan pesan peringatan yang berbeda dengan pesan yang telah dilihat dan diterima pengguna. Misalnya, kode sebelumnya mungkin menghasilkan perintah seperti ini:

Contoh perintah 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

Anda harus menghapus izin saat tidak lagi memerlukannya. Setelah izin dihapus, memanggil permissions.request() biasanya akan menambahkan kembali izin tanpa meminta 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

  • asal

    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

addHostAccessRequest()

Promise TertundaMV3+ 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Menambahkan permintaan akses host. Permintaan hanya akan diberi sinyal kepada pengguna jika ekstensi dapat diberi akses ke host dalam permintaan. Permintaan akan direset pada navigasi lintas origin. Jika diterima, akan memberikan akses persisten ke origin teratas situs

Parameter

  • minta

    objek

    • documentId

      string opsional

      ID dokumen tempat permintaan akses host dapat ditampilkan. Harus berupa dokumen tingkat teratas dalam tab. Jika disediakan, permintaan akan ditampilkan di tab dokumen yang ditentukan dan dihapus saat dokumen menavigasi ke origin baru. Menambahkan permintaan baru akan menggantikan permintaan yang ada untuk tabId. Ini atau tabId harus ditentukan.

    • pola

      string opsional

      Pola URL tempat permintaan akses host dapat ditampilkan. Jika disediakan, permintaan akses host hanya akan ditampilkan di URL yang cocok dengan pola ini.

    • tabId

      number opsional

      ID tab tempat permintaan akses host dapat ditampilkan. Jika diberikan, permintaan akan ditampilkan di tab yang ditentukan dan dihapus saat tab membuka origin baru. Menambahkan permintaan baru akan mengganti permintaan yang ada untuk documentId. Ini atau documentId harus ditentukan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

contains()

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

Memeriksa apakah ekstensi memiliki izin yang ditentukan.

Parameter

  • izin

    Izin

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result: boolean) => void

    • hasil

      boolean

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

Hasil

  • Promise<boolean>

    Chrome 96+

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getAll()

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

Mendapatkan kumpulan izin ekstensi saat ini.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (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+

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

remove()

Promise 
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: 

    (removed: boolean) => void

    • dihapus

      boolean

      Benar jika izin dihapus.

Hasil

  • Promise<boolean>

    Chrome 96+

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

removeHostAccessRequest()

Promise TertundaMV3+ 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

Menghapus permintaan akses host, jika ada.

Parameter

  • minta

    objek

    • documentId

      string opsional

      ID dokumen tempat permintaan akses host akan dihapus. Harus berupa dokumen tingkat teratas dalam tab. Ini atau tabId harus ditentukan.

    • pola

      string opsional

      Pola URL tempat permintaan akses host akan dihapus. Jika diberikan, ini harus sama persis dengan pola permintaan akses host yang ada.

    • tabId

      number opsional

      ID tab tempat permintaan akses host akan dihapus. Ini atau documentId harus ditentukan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

request()

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

Meminta akses ke izin yang ditentukan, menampilkan perintah kepada pengguna jika diperlukan. Izin ini harus ditentukan di kolom optional_permissions manifes atau merupakan izin wajib yang ditahan oleh pengguna. Jalur pada pola origin akan diabaikan. Anda dapat meminta subset izin origin opsional; misalnya, jika menentukan *://*\/* di bagian optional_permissions dalam 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: 

    (granted: boolean) => void

    • diberikan

      boolean

      Benar jika pengguna memberikan izin yang ditentukan.

Hasil

  • Promise<boolean>

    Chrome 96+

    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. Promise di-resolve dengan jenis yang sama 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: 

    (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: 

    (permissions: Permissions) => void