chrome.permissions

Açıklama

Beyan edilen isteğe bağlı izinleri yükleme zamanından ziyade çalışma zamanında istemek için chrome.permissions API'yi kullanın. Böylece kullanıcılar izinlerin neden gerekli olduğunu anlayıp yalnızca gerekli olanları verir.

Genel Bakış

API'ler tarafından verilen özellikleri açıklamak için izin uyarıları vardır ancak bu uyarılardan bazıları açık olmayabilir. İzinler API'si, geliştiricilerin izin uyarılarını açıklamalarına ve yeni özellikleri kademeli olarak tanıtmalarına olanak tanır. Bu sayede kullanıcılar uzantıyla risksiz bir şekilde tanışabilir. Böylece kullanıcılar ne kadar erişim izni vermek istediklerini ve hangi özellikleri etkinleştirmek istediklerini belirtebilir.

Örneğin, isteğe bağlı izin uzantısının temel işlevi yeni sekme sayfasını geçersiz kılıyor. Bu özelliklerden biri, kullanıcının günlük hedefini göstermesidir. Bu özellik için yalnızca depolama alanı izni gerekir. Bu izin için uyarı gösterilmez. Uzantı, kullanıcıların aşağıdaki düğmeyi tıklayarak etkinleştirebileceği ek bir özelliğe sahiptir:

Ek özellikleri etkinleştiren uzantı düğmesi

Kullanıcının en çok ziyaret ettiği siteleri göstermek için topSites izni gerekir. Bu izinle ilgili aşağıdaki uyarı gösterilir.

topSites API için uzantı uyarısı

İsteğe bağlı izinleri uygulama

1. Adım: Hangi izinlerin zorunlu, hangilerinin isteğe bağlı olduğuna karar verin

Bir uzantı hem zorunlu hem de isteğe bağlı izinler belirtebilir. Genel olarak şunları yapmalısınız:

  • Uzantınızın temel işlevi için gerekli olduğunda gerekli izinleri kullanın.
  • Uzantınızdaki isteğe bağlı özellikler için gerektiğinde isteğe bağlı izinleri kullanın.

Zorunlu izinlerin avantajları:

  • Daha az istem: Uzantı, kullanıcıdan tüm izinleri kabul etmesini bir kez isteyebilir.
  • Daha basit geliştirme: Gerekli izinlerin mevcut olduğu garanti edilir.

İsteğe bağlı izinlerin avantajları:

  • Daha iyi güvenlik: Kullanıcılar yalnızca gerekli izinleri etkinleştirdiğinden uzantılar daha az izinle çalışır.
  • Kullanıcılar için daha iyi bilgi: Kullanıcı ilgili özelliği etkinleştirdiğinde uzantı, belirli bir izne neden ihtiyaç duyduğunu açıklayabilir.
  • Daha kolay yükseltmeler: Uzantı yükseltme işleminde zorunlu izinler yerine isteğe bağlı izinler eklenirse Chrome, uzantıyı kullanıcılarınız için devre dışı bırakmaz.

2. adım: Manifestte isteğe bağlı izinleri beyan edin

İsteğe bağlı izinleri uzantı manifestinizde optional_permissions anahtarıyla izinler alanıyla aynı biçimde beyan edin:

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

Yalnızca çalışma zamanında keşfettiğiniz ana makineleri istemek istiyorsanız uzantınızın optional_host_permissions alanına "https://*/*" ekleyin. Bu sayede, eşleşen bir şeması olduğu sürece Permissions.origins alanında herhangi bir kaynağı belirtebilirsiniz.

İsteğe bağlı olarak belirtilemez izinler

Chrome uzantı izinlerinin çoğu, aşağıdaki istisnalar dışında isteğe bağlı olarak belirtilebilir.

İzin Açıklama
"debugger" chrome.debugger API'si, Chrome'un uzak hata ayıklama protokolü için alternatif bir aktarım aracı görevi görür.
"declarativeNetRequest" Uzantıya chrome.declarativeNetRequest API'sine erişim izni verir.
"devtools" Uzantının Chrome DevTools işlevini genişletmesine izin verir.
"experimental" Yalnızca Canary ve Yeni geliştirilenler kanalı Uzantı için chrome.experimental API'lerine erişim izni verir.
"geolocation" Uzantı, HTML5 coğrafi konum API'sini kullanabilir.
"mdns" Uzantıya chrome.mdns API'sine erişim izni verir.
"proxy" Chrome'un proxy ayarlarını yönetmek için uzantıya chrome.proxy API'sine erişim izni verir.
"tts" chrome.tts API'si sentezlenmiş metin okuma (TTS) oynatır.
"ttsEngine" chrome.ttsEngine API, bir uzantı kullanarak metin okuma (TTS) motoru uygular.
"wallpaper" Yalnızca ChromeOS. ChromeOS duvar kağıdını değiştirmek için chrome.wallpaper API'yi kullanın.

Mevcut izinler ve uyarıları hakkında daha fazla bilgi için İzinleri Bildirme ve Kullanıcıları Uyarma başlıklı makaleyi inceleyin.

3. adım: İsteğe bağlı izinleri isteyin

permissions.request() kullanarak kullanıcı hareketi içinden izin isteğinde bulunun:

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, izinlerin eklenmesi sonucunda daha önce gördüğü ve kabul ettiğinden farklı uyarı mesajları gösterilip gösterilmediğini sorar. Örneğin, önceki kod şu gibi bir istemle sonuçlanabilir:

örnek izin onayı istemi

4. adım: Uzantının mevcut izinlerini kontrol edin

Uzantılarınızın belirli bir izne veya izin grubuna sahip olup olmadığını kontrol etmek için 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.
  }
});

5. adım: İzinleri kaldırın

Artık ihtiyaç duymadığınız izinleri kaldırmanız gerekir. Bir izin kaldırıldıktan sonra permissions.request() çağrısı genellikle kullanıcıya sormadan izni tekrar ekler.

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).
  }
});

Türler

Permissions

Özellikler

  • köken

    string[] isteğe bağlı

    Manifest'teki optional_permissions veya permissions anahtarlarında belirtilenler ve içerik komut dosyalarıyla ilişkilendirilenler dahil olmak üzere ana makine izinlerinin listesi.

  • izinler

    string[] isteğe bağlı

    Adlandırılmış izinlerin listesi (ana makineleri veya kaynakları içermez).

Yöntemler

contains()

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

Uzantıdaki belirtilen izinleri kontrol eder.

Parametreler

  • izinler

    İzinler

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (result: boolean) => void

    • sonuç

      boolean

      Uzantı belirtilen izinlere sahipse doğru değerini döndürür. Bir kaynak hem isteğe bağlı izin hem de içerik komut dosyası eşleme kalıbı olarak belirtilirse her iki izin de verilmediği sürece false döndürülür.

İadeler

  • Promise<boolean>

    Chrome 96 ve üzeri sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

getAll()

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

Uzantının mevcut izin grubunu alır.

Parametreler

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (permissions: Permissions) => void

    • izinler

      İzinler

      Uzantının etkin izinleri. origins mülkünün, manifest'teki permissions ve optional_permissions anahtarlarında belirtilen ve İçerik Komut Dosyaları ile ilişkili olan izin verilen kaynaklarını içereceğini unutmayın.

İadeler

  • Promise<Permissions>

    Chrome 96 ve üzeri sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

remove()

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

Belirtilen izinlere erişimi kaldırır. İzinlerin kaldırılmasıyla ilgili herhangi bir sorun olursa runtime.lastError ayarlanır.

Parametreler

  • izinler

    İzinler

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (removed: boolean) => void

    • kaldırıldı

      boolean

      İzinler kaldırıldıysa doğru değerini döndürür.

İadeler

  • Promise<boolean>

    Chrome 96 ve üzeri sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

request()

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

Gerekirse kullanıcıya bir istem göstererek belirtilen izinlere erişim ister. Bu izinler, manifest'in optional_permissions alanında tanımlanmış veya kullanıcı tarafından reddedilmiş gerekli izinler olmalıdır. Kaynak kalıplarındaki yollar yoksayılır. İsteğe bağlı kaynak izinlerinin alt kümelerini isteyebilirsiniz. Örneğin, manifest'in optional_permissions bölümünde *://*\/* belirtiyorsanız http://example.com/ isteyebilirsiniz. İzin isteğinde bulunurken herhangi bir sorun oluşursa runtime.lastError ayarlanır.

Parametreler

  • izinler

    İzinler

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (granted: boolean) => void

    • izin verildi

      boolean

      Kullanıcı belirtilen izinleri verdiyse doğru değerini döndürür.

İadeler

  • Promise<boolean>

    Chrome 96 ve üzeri sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

Etkinlikler

onAdded

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

Uzantı yeni izinler aldığında tetiklenir.

Parametreler

  • geri çağırma

    işlev

    callback parametresi şu şekilde görünür: 

    (permissions: Permissions) => void

onRemoved

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

Uzantıdan izinlere erişim kaldırıldığında tetiklenir.

Parametreler

  • geri çağırma

    işlev

    callback parametresi şu şekilde görünür: 

    (permissions: Permissions) => void