browser.permissions

Açıklama

Beyan edilen isteğe bağlı izinleri yükleme zamanı yerine çalışma zamanında istemek için chrome.permissions API'sini kullanın. Böylece kullanıcılar izinlerin neden gerekli olduğunu anlayabilir ve yalnızca gerekli olan izinleri verebilir.

Kavramlar ve kullanım

İzin uyarıları, bir API tarafından sağlanan özellikleri açıklamak için kullanılır ancak bu uyarılardan bazıları net olmayabilir. Permissions API, geliştiricilerin izin uyarılarını açıklamasına ve yeni özellikleri kademeli olarak sunmasına olanak tanır. Bu sayede kullanıcılar, uzantıyı risksiz bir şekilde tanıyabilir. 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ı izinler uzantısının temel işlevi, yeni sekme sayfasını geçersiz kılmaktır. Özelliklerden biri, kullanıcının günlük hedefini gösteriyor. Bu özellik için yalnızca depolama alanı izni gerekir. Bu izin için uyarı gösterilmez. Uzantının, kullanıcıların aşağıdaki düğmeyi tıklayarak etkinleştirebileceği ek bir özelliği var:

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örüntülemek 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 gerekli, hangilerinin isteğe bağlı olduğuna karar verin

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

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

Gerekli 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 bilgiler: Bir uzantı, kullanıcı ilgili özelliği etkinleştirdiğinde neden belirli bir izne ihtiyaç duyduğunu açıklayabilir.
  • Daha kolay yükseltmeler: Uzantınızı yükselttiğinizde, yükseltme işlemi zorunlu izinler yerine isteğe bağlı izinler ekliyorsa Chrome, uzantıyı kullanıcılarınız için devre dışı bırakmaz.

2. adım: Manifest dosyasında isteğe bağlı izinleri beyan edin

Uzantı manifestinizde isteğe bağlı izinleri optional_permissions anahtarıyla, permissions alanıyla aynı biçimi kullanarak 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" içinde herhangi bir kaynak belirtebilirsiniz.

İsteğe bağlı olarak belirtilemeyen izinler

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

İzin Açıklama
"debugger" browser.debugger API, Chrome'un uzaktan hata ayıklama protokolü için alternatif bir aktarım görevi görür.
"declarativeNetRequest" Uzantıya browser.declarativeNetRequest API'sine erişim izni verir.
"devtools" Uzantının Chrome Geliştirici Araçları işlevini genişletmesine olanak tanır.
"geolocation" Uzantının HTML5 coğrafi konum API'sini kullanmasına izin verir.
"mdns" Uzantıya browser.mdns API'sine erişim izni verir.
"proxy" Chrome'un proxy ayarlarını yönetmek için uzantıya browser.proxy API'sine erişim izni verir.
"tts" browser.tts API, sentezlenmiş metin okuma (TTS) seslerini oynatır.
"ttsEngine" browser.ttsEngine API, bir uzantı kullanarak metin okuma (TTS) motoru uygular.
"wallpaper" Yalnızca ChromeOS. ChromeOS duvar kağıdını değiştirmek için browser.wallpaper API'sini kullanın.

Mevcut izinler ve uyarıları hakkında daha fazla bilgi için İzinleri Beyan Etme bölümünü inceleyin.

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

permissions.request() kullanarak bir kullanıcı hareketi içinden izinleri isteyin:

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

İzinlerin eklenmesi, kullanıcının daha önce görüp kabul ettiğinden farklı uyarı mesajlarına neden olursa Chrome kullanıcıdan onay ister. Örneğin, önceki kod aşağıdaki gibi bir istemle sonuçlanabilir:

İzin onayı istemi örneği.
Örnek bir izin onayı istemi.

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

Uzantınızın belirli bir izne veya izin grubuna sahip olup olmadığını kontrol etmek için permission.contains() kullanın:

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

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ıldığında genellikle kullanıcıya sorulmadan izin tekrar eklenir.

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

Türler

Permissions

Özellikler

  • origins

    string[] isteğe bağlı

    Manifest dosyasındaki optional_permissions veya permissions anahtarlarında belirtilenler ve içerik komut dosyalarıyla ilişkili olanlar da 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()

Chrome 133+ Chrome 148'den itibaren browser.* MV3+ 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Ana makine erişim isteği ekler. İstek, yalnızca uzantıya istekteki ana makineye erişim izni verilebiliyorsa kullanıcıya bildirilir. İstek, çapraz kaynak gezinmede sıfırlanır. Kabul edildiğinde sitenin üst kaynağına kalıcı erişim izni verir.

Parametreler

  • istek

    nesne

    • documentId

      string isteğe bağlı

      Ana makine erişim isteklerinin gösterilebileceği bir dokümanın kimliği. Sekmedeki en üst düzey doküman 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 eklediğinizde tabId için mevcut istekler geçersiz kılınır. Bu veya tabId belirtilmelidir.

    • desen

      string 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 eklediğinizde documentId için mevcut bir isteği geçersiz kılarsınız. Bu veya documentId belirtilmelidir.

İadeler

  • Promise<void>

contains()

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

Uzantının belirtilen izinlere sahip olup olmadığını kontrol eder.

Parametreler

İadeler

  • Promise<boolean>

    Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

getAll()

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

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

İadeler

  • Promise<Permissions>

    Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

remove()

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

Belirtilen izinlere erişimi kaldırır. İzinler kaldırılırken sorun yaşanırsa vaat reddedilir.

Parametreler

İadeler

  • Promise<boolean>

    Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

removeHostAccessRequest()

Chrome 133+ Chrome 148'den itibaren browser.* MV3+ 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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

Parametreler

  • istek

    nesne

    • documentId

      string isteğe bağlı

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

    • desen

      string isteğe bağlı

      Ana makine erişim isteğinin kaldırılacağı URL kalıbı. Sağlanmışsa mevcut bir ana makine erişim isteğinin kalıbıyla 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.

İadeler

  • Promise<void>

request()

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

Belirtilen izinlere erişim isteğinde bulunur ve gerekirse kullanıcıya bir istem gösterir. Bu izinler, manifest dosyasının optional_permissions alanında tanımlanmalı veya kullanıcı tarafından reddedilen 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 dosyasının optional_permissions bölümünde *://*\/* değerini belirtirseniz http://example.com/ değerini isteyebilirsiniz. İzinleri istemeyle ilgili herhangi bir sorun varsa vaat reddedilir.

Parametreler

İadeler

  • Promise<boolean>

    Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

Etkinlikler

onAdded

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

Uzantı yeni izinler aldığında tetiklenir.

Parametreler

  • callback

    işlev

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

    (permissions: Permissions) => void

onRemoved

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

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

Parametreler

  • callback

    işlev

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

    (permissions: Permissions) => void