chrome.permissions

Deskripsi

Gunakan API chrome.permissions 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. Permissions API memungkinkan developer menjelaskan peringatan izin dan memperkenalkan fitur baru secara bertahap sehingga pengguna dapat mencoba ekstensi tanpa risiko. Dengan begitu, pengguna dapat menentukan jumlah akses yang ingin mereka berikan dan fitur yang ingin mereka aktifkan.

Misalnya, fungsi inti ekstensi izin opsional adalah mengganti halaman tab baru. Salah satu fitur menampilkan sasaran pengguna untuk hari itu. 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 wajib jika diperlukan untuk fungsi dasar ekstensi Anda.
Gunakan izin opsional jika diperlukan untuk fitur opsional di ekstensi Anda.

Keuntungan izin wajib:

Lebih sedikit dialog: Ekstensi dapat meminta pengguna untuk menyetujui semua izin satu kali.
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 izin tertentu diperlukan 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 wajib.

Langkah 2: Mendeklarasikan 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. Dengan begitu, Anda dapat menentukan asal mana 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"`	API chrome.debugger berfungsi sebagai transport alternatif untuk protokol pen-debugan jarak jauh Chrome.
`"declarativeNetRequest"`	Memberi ekstensi akses ke chrome.declarativeNetRequest API.
`"devtools"`	Mengizinkan ekstensi memperluas fungsi Chrome DevTools. functionality.
`"geolocation"`	Mengizinkan ekstensi menggunakan HTML5 geolocation API.
`"mdns"`	Memberi ekstensi akses ke chrome.mdns API.
`"proxy"`	Memberi ekstensi akses ke API chrome.proxy untuk mengelola setelan proxy Chrome.
`"tts"`	API chrome.tts memutar text-to-speech (TTS) yang disintesis.
`"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 penambahan izin menghasilkan pesan peringatan yang berbeda dengan yang telah dilihat dan disetujui pengguna. Misalnya, kode sebelumnya dapat menghasilkan perintah seperti ini:

Langkah 4: Periksa izin saat ini ekstensi

Untuk memeriksa apakah ekstensi Anda memiliki izin tertentu atau sekumpulan izin, 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 menyertakan host atau origin).

Metode

addHostAccessRequest()

Chrome 133+ MV3+

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

Menambahkan permintaan akses host. Permintaan hanya akan disinyalkan kepada pengguna jika ekstensi dapat diberi akses ke host dalam permintaan. Permintaan akan direset pada navigasi lintas origin. Jika diterima, memberikan akses persisten ke asal 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 membuka asal 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
  
  nomor opsional
  
  ID tab tempat permintaan akses host dapat ditampilkan. Jika disediakan, 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()

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

Memeriksa apakah ekstensi memiliki izin yang ditentukan.

Parameter

izin

Izin

Hasil

Promise<boolean>

Chrome 96+

getAll()

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

Mendapatkan kumpulan izin ekstensi saat ini.

Hasil

Promise<Permissions>

Chrome 96+

remove()

chrome.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+

removeHostAccessRequest()

Chrome 133+ MV3+

chrome.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, nilai ini harus sama persis dengan pola permintaan akses host yang ada.
- tabId
  
  nomor opsional
  
  ID tab tempat permintaan akses host akan dihapus. Ini atau documentId harus ditentukan.

Hasil

Promise<void>

request()

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

Meminta akses ke izin yang ditentukan, menampilkan perintah kepada pengguna jika perlu. Izin ini harus ditentukan di kolom optional_permissions pada manifes atau merupakan izin yang diperlukan yang ditahan oleh pengguna. Jalur pada pola origin akan diabaikan. Anda dapat meminta subset izin asal 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+

Acara

onAdded

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

Diaktifkan saat ekstensi memperoleh izin baru.

Parameter

callback

fungsi

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

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
```
- izin
  
  Izin

chrome.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: Mendeklarasikan izin opsional dalam manifes

Langkah 3: Minta izin opsional

Langkah 4: Periksa izin saat ini ekstensi

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

chrome.permissions