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.

Kavramlar ve kullanım

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 bir uzantı düğmesi.
Ek özellikleri etkinleştiren bir 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ı.
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, eşleşen bir şeması olduğu sürece "Permissions.origins" içindeki herhangi bir kaynağı belirtmenize olanak tanır.

İ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.
"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 beyan etme 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.
Ö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

addHostAccessRequest()

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

Ana makine erişim isteği ekler. İstek yalnızca uzantıya istekteki ana makineye erişim izni verilebiliyorsa kullanıcıya sinyal gönderilir. İstek, kaynakta gezinme sırasında sıfırlanır. Kabul edildiğinde, sitenin üst kaynağına kalıcı erişim izni verir

Parametreler

  • istek

    nesne

    • documentId

      dize isteğe bağlı

      Ana makine erişim isteklerinin gösterilebileceği bir dokümanın kimliği. Bir sekmedeki üst düzey belge olmalıdır. Sağlanırsa istek, belirtilen dokümanın sekmesinde gösterilir ve doküman yeni bir kaynağa gittiğinde kaldırılır. Yeni bir istek eklemek, tabId için mevcut tüm istekleri geçersiz kılar. Bu veya tabId belirtilmelidir.

    • desen

      dize isteğe bağlı

      Ana makine erişim isteklerinin gösterilebileceği URL kalıbı. Sağlanırsa ana makine erişim istekleri yalnızca bu kalıpla eşleşen URL'lerde gösterilir.

    • tabId

      number isteğe bağlı

      Ana makine erişim isteklerinin gösterilebileceği sekmenin kimliği. Sağlanırsa istek, belirtilen sekmede gösterilir ve sekme yeni bir kaynağa gittiğinde kaldırılır. Yeni bir istek eklendiğinde documentId için mevcut istek geçersiz kılınır. Bu veya documentId belirtilmelidir.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Promise<void>

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

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 Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

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 Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

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 Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

removeHostAccessRequest()

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

Varsa ana makine erişim isteğini kaldırır.

Parametreler

  • istek

    nesne

    • documentId

      dize isteğe bağlı

      Ana makine erişim isteğinin kaldırılacağı dokümanın kimliği. Bir sekmedeki üst düzey belge olmalıdır. Bu veya tabId belirtilmelidir.

    • desen

      dize isteğe bağlı

      Ana makine erişim isteğinin kaldırılacağı URL kalıbı. Bu değer sağlanırsa mevcut bir ana makine erişim isteğiyle tam olarak eşleşmelidir.

    • tabId

      number isteğe bağlı

      Ana makine erişim isteğinin kaldırılacağı sekmenin kimliği. Bu veya documentId belirtilmelidir.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Promise<void>

    Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

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 Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

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