Descrizione
Utilizza l'API chrome.permissions
per richiedere le autorizzazioni facoltative dichiarate in fase di esecuzione, anziché di installazione, in modo che gli utenti capiscano perché le autorizzazioni sono necessarie e concedino solo quelle necessarie.
Panoramica
Esistono avvisi di autorizzazione per descrivere le funzionalità concesse da un'API, ma alcuni di questi avvisi potrebbero non essere evidenti. L'API Permissions consente agli sviluppatori di spiegare gli avvisi di autorizzazione e di introdurre gradualmente le nuove funzionalità, offrendo così agli utenti un'introduzione all'estensione senza rischi. In questo modo, gli utenti possono specificare il livello di accesso che sono disposti a concedere e le funzionalità che desiderano abilitare.
Ad esempio, la funzionalità di base dell'estensione Autorizzazioni facoltative sostituisce la pagina Nuova scheda. Una funzionalità mostra l'obiettivo della giornata dell'utente. Questa funzionalità richiede solo l'autorizzazione per lo spazio di archiviazione, che non include un avviso. L'estensione include una funzionalità aggiuntiva, che gli utenti possono attivare facendo clic sul seguente pulsante:
Per visualizzare i siti principali dell'utente è necessaria l'autorizzazione topSites, che presenta il seguente avviso.
Implementare le autorizzazioni facoltative
Passaggio 1: decidi quali autorizzazioni sono necessarie e quali facoltative
Un'estensione può dichiarare autorizzazioni sia obbligatorie che facoltative. In generale, devi:
- Utilizza le autorizzazioni richieste quando sono necessarie per la funzionalità di base dell'estensione.
- Utilizza le autorizzazioni facoltative quando sono necessarie per le funzionalità facoltative nell'estensione.
Vantaggi delle autorizzazioni obbligatorie:
- Meno richieste:un'estensione può chiedere all'utente una volta di accettare tutte le autorizzazioni.
- Sviluppo più semplice:è garantita la presenza delle autorizzazioni richieste.
Vantaggi delle autorizzazioni facoltative:
- Maggiore sicurezza: le estensioni vengono eseguite con meno autorizzazioni in quanto gli utenti attivano solo le autorizzazioni necessarie.
- Informazioni migliori per gli utenti: un'estensione può spiegare perché è necessaria un'autorizzazione specifica quando l'utente attiva la funzionalità pertinente.
- Upgrade più semplici: quando esegui l'upgrade dell'estensione, Chrome non la disattiverà per i tuoi utenti se l'upgrade aggiunge autorizzazioni facoltative anziché obbligatorie.
Passaggio 2: dichiara le autorizzazioni facoltative nel file manifest
Dichiara le autorizzazioni facoltative nel manifest delle estensioni con la chiave optional_permissions
, utilizzando lo stesso formato del campo permissions:
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
Se vuoi richiedere host che rilevi solo in fase di runtime, includi "https://*/*"
nel campo optional_host_permissions
dell'estensione. In questo modo puoi specificare qualsiasi origine in Permissions.origins purché abbia uno schema corrispondente.
Autorizzazioni che non possono essere specificate come facoltative
La maggior parte delle autorizzazioni per le estensioni di Chrome può essere specificata come facoltativa, con le seguenti eccezioni.
Autorizzazione | Descrizione |
---|---|
"debugger" |
L'API chrome.debugger funge da trasporto alternativo per il protocollo di debug remoto di Chrome. |
"declarativeNetRequest" |
Concede all'estensione l'accesso all'API chrome.declarativeNetRequest. |
"devtools" |
Consente all'estensione di espandere la funzionalità di Chrome DevTools. |
"experimental" |
Solo per i canali Canary e Dev. Concede all'estensione l'accesso alle API chrome.experimental. |
"geolocation" |
Consente all'estensione di utilizzare l'API di geolocation HTML5. |
"mdns" |
Concede all'estensione l'accesso all'API chrome.mdns. |
"proxy" |
Concede all'estensione l'accesso all'API chrome.proxy per gestire le impostazioni proxy di Chrome. |
"tts" |
L'API chrome.tts riproduce la sintesi vocale (TTS). |
"ttsEngine" |
L'API chrome.ttsEngine implementa un motore di sintesi vocale (TTS) utilizzando un'estensione. |
"wallpaper" |
Solo ChromeOS. Utilizza l'API chrome.wallpaper per modificare lo sfondo di ChromeOS. |
Per ulteriori informazioni sulle autorizzazioni disponibili e sui relativi avvisi, consulta Dichiara le autorizzazioni e avvisa gli utenti.
Passaggio 3: richiedi autorizzazioni facoltative
Richiedi le autorizzazioni dall'interno di un gesto dell'utente utilizzando 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 chiede all'utente se l'aggiunta delle autorizzazioni genera messaggi di avviso diversi da quelli che l'utente ha già visto e accettato. Ad esempio, il codice precedente potrebbe generare un prompt simile al seguente:
Passaggio 4: verifica le autorizzazioni correnti dell'estensione
Per verificare se l'estensione ha un'autorizzazione o un insieme di autorizzazioni specifici, utilizza
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.
}
});
Passaggio 5: rimuovi le autorizzazioni
Dovresti rimuovere le autorizzazioni quando non ti servono più. Dopo la rimozione di un'autorizzazione, la chiamata a permissions.request()
in genere ne aggiunge di nuovo l'autorizzazione senza chiedere conferma all'utente.
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).
}
});
Tipi
Permissions
Proprietà
-
origini
string[] facoltativo
L'elenco delle autorizzazioni host, incluse quelle specificate nelle chiavi
optional_permissions
opermissions
del file manifest, e quelle associate agli script di contenuti. -
autorizzazioni
string[] facoltativo
Elenco di autorizzazioni denominate (non include host o origini).
Metodi
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
Controlla se l'estensione dispone delle autorizzazioni specificate.
Parametri
-
autorizzazioni
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: boolean) => void
-
risultato
boolean
True se l'estensione dispone delle autorizzazioni specificate. Se un'origine viene specificata sia come autorizzazione facoltativa sia come pattern di corrispondenza per lo script dei contenuti, verrà restituito
false
a meno che non vengano concesse entrambe le autorizzazioni.
-
Ritorni
-
Promise<boolean>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getAll()
chrome.permissions.getAll(
callback?: function,
)
Recupera l'insieme di autorizzazioni corrente dell'estensione.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(permissions: Permissions) => void
-
autorizzazioni
Le autorizzazioni attive dell'estensione. Tieni presente che la proprietà
origins
conterrà le origini concesse da quelle specificate nelle chiavipermissions
eoptional_permissions
nel file manifest e da quelle associate agli script di contenuti.
-
Ritorni
-
Promessa<Autorizzazioni>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
Rimuove l'accesso alle autorizzazioni specificate. In caso di problemi con la rimozione delle autorizzazioni, verrà impostato runtime.lastError
.
Parametri
-
autorizzazioni
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(removed: boolean) => void
-
rimosso
boolean
True se le autorizzazioni sono state rimosse.
-
Ritorni
-
Promise<boolean>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
Richiede l'accesso alle autorizzazioni specificate, mostrando una richiesta all'utente, se necessario. Queste autorizzazioni devono essere definite nel campo optional_permissions
del manifest o devono essere le autorizzazioni obbligatorie che sono state trattenute dall'utente. I percorsi sui pattern di origine verranno ignorati. Puoi richiedere sottoinsiemi di autorizzazioni per l'origine facoltative; ad esempio, se specifichi *://*\/*
nella sezione optional_permissions
del manifest, puoi richiedere http://example.com/
. In caso di problemi con la richiesta delle autorizzazioni, verrà impostato runtime.lastError
.
Parametri
-
autorizzazioni
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(granted: boolean) => void
-
concessa
boolean
True se l'utente ha concesso le autorizzazioni specificate.
-
Ritorni
-
Promise<boolean>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
Eventi
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
Attivato quando l'estensione acquisisce nuove autorizzazioni.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(permissions: Permissions) => void
-
autorizzazioni
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
Attivato quando l'accesso alle autorizzazioni è stato rimosso dall'estensione.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(permissions: Permissions) => void
-
autorizzazioni
-