Chrome kini mendukung namespace browser.* standar (tersedia mulai Chrome 148). Kami memperbarui dokumentasi secara bertahap. Baca selengkapnya di panduan transisi kami.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

browser.permissions

Deskripsi

Gunakan chrome.permissions API untuk meminta izin opsional yang dideklarasikan saat runtime, bukan saat 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 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 adalah mengganti halaman tab baru. Salah satu fiturnya adalah 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.

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 mana yang diperlukan dan mana yang 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.

Keuntungan izin yang diperlukan:

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

Keuntungan 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 ekstensi 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 Anda 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. Dengan begitu, Anda dapat menentukan origin apa pun di "Permissions.origins" asalkan 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"`	API browser.debugger berfungsi sebagai transportasi alternatif untuk protokol proses debug jarak jauh Chrome.
`"declarativeNetRequest"`	Memberikan akses ekstensi ke API browser.declarativeNetRequest.
`"devtools"`	Memungkinkan ekstensi memperluas fungsi Chrome DevTools.
`"geolocation"`	Mengizinkan ekstensi menggunakan API geolokasi HTML5.
`"mdns"`	Memberikan akses ekstensi ke API browser.mdns.
`"proxy"`	Memberikan akses ekstensi ke API browser.proxy untuk mengelola setelan proxy Chrome.
`"tts"`	browser.tts API memutar text-to-speech (TTS) yang disintesis.
`"ttsEngine"`	browser.ttsEngine API mengimplementasikan mesin text-to-speech (TTS) menggunakan ekstensi.
`"wallpaper"`	Khusus ChromeOS. Gunakan API browser.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.
  browser.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 penambahan izin menghasilkan pesan peringatan yang berbeda dari yang telah dilihat dan diterima pengguna. Misalnya, kode sebelumnya mungkin menghasilkan perintah seperti ini:

Langkah 4: Periksa izin ekstensi saat ini

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

browser.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 jika tidak lagi memerlukannya. Setelah izin dihapus, memanggil permissions.request() biasanya akan menambahkan kembali izin tanpa meminta pengguna.

browser.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

origins

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

Chrome 133+ browser.* sejak Chrome 148 MV3+

browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Menambahkan permintaan akses host. Permintaan hanya akan dikirimkan kepada pengguna jika ekstensi dapat diberi akses ke host dalam permintaan. Permintaan akan direset pada navigasi lintas origin. Jika diterima, 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 diberikan, permintaan akan ditampilkan di tab dokumen yang ditentukan dan dihapus saat dokumen membuka 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 diberikan, 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 menggantikan permintaan yang ada untuk documentId. Ini atau documentId harus ditentukan.

Hasil

Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

Memeriksa apakah ekstensi memiliki izin yang ditentukan.

Parameter

izin

Izin

Hasil

Promise<boolean>

Chrome 96+ browser.* sejak Chrome 148

getAll()

browser.permissions.getAll(): Promise<Permissions>

Mendapatkan kumpulan izin ekstensi saat ini.

Hasil

Promise<Permissions>

Chrome 96+ browser.* sejak Chrome 148

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

Menghapus akses ke izin yang ditentukan. Jika ada masalah saat menghapus izin, promise akan ditolak.

Parameter

izin

Izin

Hasil

Promise<boolean>

Chrome 96+ browser.* sejak Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* sejak Chrome 148 MV3+

browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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, pola 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.

Hasil

Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

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

Parameter

izin

Izin

Hasil

Promise<boolean>

Chrome 96+ browser.* sejak Chrome 148

Acara

onAdded

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

Diaktifkan saat ekstensi memperoleh izin baru.

Parameter

callback

fungsi

Parameter callback terlihat seperti:
```
(permissions: Permissions) => void
```
- izin
  
  Izin

onRemoved

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

Diaktifkan saat akses ke izin telah dihapus dari ekstensi.

Parameter

callback

fungsi

Parameter callback terlihat seperti:
```
(permissions: Permissions) => void
```
- izin
  
  Izin

browser.permissions Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Deskripsi

Konsep dan penggunaan

Menerapkan izin opsional

Langkah 1: Tentukan izin mana yang diperlukan dan mana yang opsional

Langkah 2: Deklarasikan izin opsional dalam manifes

Langkah 3: Minta izin opsional

Langkah 4: Periksa izin ekstensi saat ini

Langkah 5: Hapus izin

Jenis

Permissions

Properti

Metode

addHostAccessRequest()

Parameter

Hasil

contains()

Parameter

Hasil

getAll()

Hasil

remove()

Parameter

Hasil

removeHostAccessRequest()

Parameter

Hasil

request()

Parameter

Hasil

Acara

onAdded

Parameter

onRemoved

Parameter

browser.permissions