Descrizione
Usa l'API chrome.cookies
per eseguire query e modificare i cookie e per ricevere una notifica quando cambiano.
Autorizzazioni
cookies
Per utilizzare l'API dei cookie, dichiara l'autorizzazione "cookies"
nel file manifest insieme alle autorizzazioni host per gli host di cui vuoi accedere ai cookie. Ad esempio:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
Partizionamento
I cookie partizionati consentono a un sito di contrassegnare che determinati cookie devono essere inseriti in base all'origine del frame di primo livello. Ciò significa che, ad esempio, se il sito A viene incorporato utilizzando un iframe nel sito B e nel sito C, le versioni incorporate di un cookie partizionato da A possono avere valori diversi su B e C.
Per impostazione predefinita, tutti i metodi dell'API operano su cookie non partizionati. La
proprietà partitionKey
può essere utilizzata per ignorare questo comportamento.
Per maggiori dettagli sull'impatto generale del partizionamento per le estensioni, consulta Spazio di archiviazione e cookie.
Esempi
Puoi trovare un semplice esempio di utilizzo dell'API cookie nella directory examples/api/cookies. Per altri esempi e per assistenza sulla visualizzazione del codice sorgente, consulta la pagina Esempi.
Tipi
Cookie
Rappresenta le informazioni su un cookie HTTP.
Proprietà
-
dominio
stringa
Il dominio del cookie (ad es. "www.google.com", "example.com").
-
expirationDate
numero facoltativo
La data di scadenza del cookie come numero di secondi dall'epoca di UNIX. Non fornito per i cookie di sessione.
-
hostOnly
boolean
True se il cookie è un cookie solo host (ovvero l'host di una richiesta deve corrispondere esattamente al dominio del cookie).
-
httpOnly
boolean
True se il cookie è contrassegnato come HttpOnly (ovvero il cookie non è accessibile agli script lato client).
-
nome
stringa
Il nome del cookie.
-
partitionKey
CookiePartitionKey facoltativo
Chrome 119 e versioni successiveLa chiave di partizione per leggere o modificare i cookie con l'attributo Partitioned.
-
percorso
stringa
Il percorso del cookie.
-
sameSiteChrome 51 e versioni successive
Lo stato dello stesso sito del cookie (ovvero se il cookie viene inviato con richieste cross-site).
-
sicuro
boolean
True se il cookie è contrassegnato come sicuro (ossia il suo ambito è limitato ai canali sicuri, in genere HTTPS).
-
sessione
boolean
True se il cookie è un cookie di sessione, anziché un cookie permanente con una data di scadenza.
-
storeId
stringa
L'ID dell'archivio di cookie che contiene il cookie, come fornito in getAllCookieStores().
-
valore
stringa
Il valore del cookie.
CookieDetails
Dettagli per identificare il cookie.
Proprietà
-
nome
stringa
Il nome del cookie a cui accedere.
-
partitionKey
CookiePartitionKey facoltativo
Chrome 119 e versioni successiveLa chiave di partizione per leggere o modificare i cookie con l'attributo Partitioned.
-
storeId
stringa facoltativo
L'ID dell'archivio di cookie in cui cercare il cookie. Per impostazione predefinita, viene utilizzato l'archivio dei cookie del contesto di esecuzione corrente.
-
url
stringa
L'URL a cui è associato il cookie per l'accesso. Questo argomento può essere un URL completo, nel qual caso tutti i dati che seguono il percorso dell'URL (ad esempio la stringa di query) vengono semplicemente ignorati. Se le autorizzazioni dell'host per questo URL non sono specificate nel file manifest, la chiamata API non andrà a buon fine.
CookiePartitionKey
Rappresenta la chiave di partizione di un cookie partizionato.
Proprietà
-
topLevelSite
stringa facoltativo
Il sito di primo livello in cui è disponibile il cookie partizionato.
CookieStore
Rappresenta un archivio di cookie nel browser. Ad esempio, una finestra in modalità di navigazione in incognito utilizza un archivio di cookie separato da una finestra non di navigazione in incognito.
Proprietà
-
id
stringa
L'identificatore univoco dell'archivio dei cookie.
-
tabIds
numero[]
Identificatori di tutte le schede del browser che condividono questo archivio dei cookie.
OnChangedCause
Il motivo alla base della modifica del cookie. Se un cookie è stato inserito o rimosso tramite una chiamata esplicita a "chrome.cookies.remove", la causa "cause" sarà "esplicita". Se un cookie è stato rimosso automaticamente in seguito alla scadenza, la causa "causa" sarà "scaduta". Se un cookie è stato rimosso perché è stato sovrascritto con una data di scadenza già scaduta, "cause" verrà impostato su "expired_overwrite". Se un cookie è stato rimosso automaticamente a causa di una garbage collection, la "causa" sarà "rimossa". Se un cookie è stato rimosso automaticamente a causa di una chiamata "set" che lo ha sovrascritto, "causa" sarà "sovrascrittura". Pianifica la tua risposta di conseguenza.
Enum
"expired_overwrite"
SameSiteStatus
Lo stato "SameSite" di un cookie (https://tools.ietf.org/html/Draft-west-first-party-cookies). "no_restriction" corrisponde a un cookie impostato con "SameSite=None", da "lax" a "SameSite=Lax" e "strict" su "SameSite=Strict". "non specificato" corrisponde a un cookie impostato senza l'attributo SameSite.
Enum
"no_restriction"
"lax"
"strict"
Metodi
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
Recupera le informazioni su un singolo cookie. Se esiste più di un cookie con lo stesso nome per l'URL specificato, verrà restituito quello con il percorso più lungo. Per i cookie con la stessa lunghezza di percorso, verrà restituito il cookie con la prima data/ora di creazione.
Parametri
Ritorni
-
Promise<Cookie | undefined>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
Recupera tutti i cookie da un unico archivio che corrispondono alle informazioni fornite. I cookie restituiti verranno ordinati, partendo da quelli con il percorso più lungo. Se più cookie hanno la stessa lunghezza del percorso, quelli con la data e l'ora di creazione meno recenti vengono mostrati per primi. Questo metodo recupera solo i cookie per i domini per i quali l'estensione dispone delle autorizzazioni per l'host.
Parametri
-
dettagli
oggetto
Informazioni per filtrare i cookie recuperati.
-
dominio
stringa facoltativo
Limita i cookie recuperati a quelli i cui domini corrispondono o sono sottodomini di questo.
-
nome
stringa facoltativo
Filtra i cookie per nome.
-
partitionKey
CookiePartitionKey facoltativo
Chrome 119 e versioni successiveLa chiave di partizione per leggere o modificare i cookie con l'attributo Partitioned.
-
percorso
stringa facoltativo
Limita i cookie recuperati a quelli il cui percorso corrisponde esattamente a questa stringa.
-
sicuro
booleano facoltativo
Filtra i cookie in base alla relativa proprietà Secure.
-
sessione
booleano facoltativo
Filtra i cookie di sessione e quelli permanenti.
-
storeId
stringa facoltativo
L'archivio di cookie da cui recuperare i cookie. Se omesso, verrà utilizzato l'archivio di cookie del contesto di esecuzione corrente.
-
url
stringa facoltativo
Limita i cookie recuperati a quelli che corrispondono all'URL specificato.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(cookies: Cookie[]) => void
-
cookie
Biscotto[]
Tutti i cookie esistenti non scaduti che corrispondono alle informazioni dei cookie specificate.
-
Ritorni
-
Promise<Cookie[]>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Elenca tutti gli archivi di cookie esistenti.
Parametri
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(cookieStores: CookieStore[]) => void
-
cookieStores
Tutti gli archivi di cookie esistenti.
-
Ritorni
-
Promise<CookieStore[]>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Elimina un cookie in base al nome.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(details?: object) => void
-
dettagli
oggetto facoltativo
Contiene i dettagli del cookie che è stato rimosso. Se per qualsiasi motivo la rimozione non riesce, il valore sarà "null" e verrà impostato
runtime.lastError
.-
nome
stringa
Il nome del cookie che è stato rimosso.
-
partitionKey
CookiePartitionKey facoltativo
Chrome 119 e versioni successiveLa chiave di partizione per leggere o modificare i cookie con l'attributo Partitioned.
-
storeId
stringa
L'ID dell'archivio di cookie da cui è stato rimosso.
-
url
stringa
L'URL associato al cookie che è stato rimosso.
-
-
Ritorni
-
Promise<object | undefined>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
Imposta un cookie con i dati specificati; i cookie equivalenti potrebbero essere sovrascritti, se presenti.
Parametri
-
dettagli
oggetto
Dettagli sul cookie impostato.
-
dominio
stringa facoltativo
Il dominio del cookie. Se omesso, il cookie diventa un cookie solo host.
-
expirationDate
numero facoltativo
La data di scadenza del cookie come numero di secondi dall'epoca di UNIX. Se omesso, diventa un cookie di sessione.
-
httpOnly
booleano facoltativo
Indica se il cookie deve essere contrassegnato come HttpOnly. Il valore predefinito è false.
-
nome
stringa facoltativo
Il nome del cookie. Vuoto per impostazione predefinita se omesso.
-
partitionKey
CookiePartitionKey facoltativo
Chrome 119 e versioni successiveLa chiave di partizione per leggere o modificare i cookie con l'attributo Partitioned.
-
percorso
stringa facoltativo
Il percorso del cookie. Il valore predefinito è la parte del percorso del parametro url.
-
sameSite
Facoltativo SameSiteStatus
Chrome 51 e versioni successiveLo stato dello stesso sito del cookie. Il valore predefinito è "non specificato", ovvero se omesso, il cookie viene impostato senza specificare un attributo SameSite.
-
sicuro
booleano facoltativo
Indica se il cookie deve essere contrassegnato come sicuro. Il valore predefinito è false.
-
storeId
stringa facoltativo
L'ID dell'archivio cookie in cui impostarlo. Per impostazione predefinita, il cookie viene impostato nell'archivio dei cookie del contesto di esecuzione corrente.
-
url
stringa
L'URI della richiesta da associare all'impostazione del cookie. Questo valore può influire sui valori predefiniti del dominio e del percorso del cookie creato. Se le autorizzazioni dell'host per questo URL non sono specificate nel file manifest, la chiamata API non andrà a buon fine.
-
valore
stringa facoltativo
Il valore del cookie. Vuoto per impostazione predefinita se omesso.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(cookie?: Cookie) => void
-
biscotto
Cookie facoltativo
Contiene i dettagli del cookie impostato. Se per qualsiasi motivo l'impostazione non riesce, il valore sarà "nullo" e verrà impostato
runtime.lastError
.
-
Ritorni
-
Promise<Cookie | undefined>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
Eventi
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Attivato quando un cookie viene impostato o rimosso. Come caso speciale, tieni presente che l'aggiornamento delle proprietà di un cookie avviene come un processo in due fasi: il cookie da aggiornare viene prima rimosso completamente, generando una notifica con "causa" di "overwrite" . In seguito, viene scritto un nuovo cookie con i valori aggiornati, generando una seconda notifica con "cause" "explicit".
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(changeInfo: object) => void
-
changeInfo
oggetto
-
cause
Il motivo alla base della modifica del cookie.
-
biscotto
Informazioni sul cookie impostato o rimosso.
-
rimossa
boolean
True se un cookie è stato rimosso.
-
-