chrome.cookies

Descrizione

Utilizza l'API chrome.cookies per eseguire query e modificare i cookie e per ricevere una notifica quando cambiano.

Autorizzazioni

cookies

Per utilizzare l'API cookies, dichiara l'autorizzazione "cookies" nel manifest insieme alle autorizzazioni host per tutti gli host ai cui cookie vuoi accedere. Ad esempio:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

Partizionamento

I cookie con stato partizionato consentono a un sito di contrassegnare determinati cookie come correlati all'origine del frame di primo livello. Ciò significa che, ad esempio, se il sito A è incorporato utilizzando un iframe nel sito B e nel sito C, le versioni incorporate di un cookie partizionato di A possono avere valori diversi su B e C.

Per impostazione predefinita, tutti i metodi dell'API operano su cookie non suddivisi. La proprietà partitionKey può essere utilizzata per eseguire l'override di questo comportamento.

Per informazioni dettagliate sull'impatto generale del partizionamento per le estensioni, consulta Spazio di archiviazione e cookie.

Esempi

Puoi trovare un semplice esempio di utilizzo dell'API cookies nella directory examples/api/cookies. Per altri esempi e per assistenza per la visualizzazione del codice sorgente, consulta Samples.

Tipi

Rappresenta le informazioni su un cookie HTTP.

Proprietà

  • dominio

    stringa

    Il dominio del cookie (ad es. "www.google.com", "example.com").

  • expirationDate

    number facoltativo

    La data di scadenza del cookie come numero di secondi dall'epoca UNIX. Non fornito per i cookie di sessione.

  • hostOnly

    booleano

    True se il cookie è un cookie solo host (ovvero l'host di una richiesta deve corrispondere esattamente al dominio del cookie).

  • httpOnly

    booleano

    True se il cookie è contrassegnato come HttpOnly (ovvero non è accessibile agli script lato client).

  • nome

    stringa

    Il nome del cookie.

  • partitionKey

    CookiePartitionKey facoltativo

    Chrome 119 e versioni successive

    La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

  • percorso

    stringa

    Il percorso del cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 e versioni successive

    Lo stato same-site del cookie (ovvero se il cookie viene inviato con richieste cross-site).

  • sicuro

    booleano

    True se il cookie è contrassegnato come sicuro (ovvero il suo ambito è limitato ai canali sicuri, in genere HTTPS).

  • sessione

    booleano

    Vero se il cookie è un cookie della sessione, a differenza di un cookie persistente con una data di scadenza.

  • storeId

    stringa

    L'ID dell'archivio dei cookie contenente questo cookie, come fornito in getAllCookieStores().

  • valore

    stringa

    Il valore del cookie.

CookieDetails

Chrome 88 e versioni successive

Dettagli per identificare il cookie.

Proprietà

  • nome

    stringa

    Il nome del cookie a cui accedere.

  • partitionKey

    CookiePartitionKey facoltativo

    Chrome 119 e versioni successive

    La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

  • storeId

    stringa facoltativa

    L'ID del cookie store in cui cercare il cookie. Per impostazione predefinita, verrà utilizzato l'archivio dei cookie del contesto di esecuzione corrente.

  • url

    stringa

    L'URL a cui è associato il cookie a cui accedere. Questo parametro può essere un URL completo, nel qual caso tutti i dati che seguono il percorso dell'URL (ad es. la stringa di query) vengono semplicemente ignorati. Se le autorizzazioni host per questo URL non sono specificate nel file manifest, la chiamata all'API non andrà a buon fine.

CookiePartitionKey

Chrome 119 e versioni successive

Rappresenta la chiave di partizione di un cookie partizionato.

Proprietà

  • hasCrossSiteAncestor

    booleano facoltativo

    Chrome 130 e versioni successive

    Indica se il cookie è stato impostato in un contesto di siti cross-cross. In questo modo, un sito di primo livello incorporato in un contesto cross-site non può accedere ai cookie impostati dal sito di primo livello in un contesto same-site.

  • topLevelSite

    stringa facoltativa

    Il sito di primo livello in cui è disponibile il cookie partizionato.

CookieStore

Rappresenta un archivio dei cookie nel browser. Una finestra in modalità di navigazione in incognito, ad esempio, utilizza un archivio dei cookie separato da una finestra non in incognito.

Proprietà

  • id

    stringa

    L'identificatore univoco per il cookie store.

  • tabIds

    number[]

    Identificatori di tutte le schede del browser che condividono questo archivio cookie.

FrameDetails

In attesa

Dettagli per identificare il frame.

Proprietà

  • documentId

    stringa facoltativa

    L'identificatore univoco del documento. Se vengono forniti frameId e/o tabId, verranno convalidati in modo che corrispondano al documento trovato dall'ID documento fornito.

  • frameId

    number facoltativo

    L'identificatore univoco del frame all'interno della scheda.

  • tabId

    number facoltativo

    L'identificatore univoco della scheda contenente il frame.

OnChangedCause

Chrome 44 e versioni successive

Il motivo alla base della modifica del cookie. Se un cookie è stato inserito o rimosso tramite una chiamata esplicita a "chrome.cookies.remove", "cause" sarà "explicit". Se un cookie è stato rimosso automaticamente a causa della scadenza, "cause" sarà "expired". 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 della raccolta dei rifiuti, "cause" sarà "evicted". Se un cookie è stato rimosso automaticamente a causa di una chiamata "set" che lo ha sovrascritto, "cause" sarà "overwrite". Pianifica la tua risposta di conseguenza.

Enum

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 e versioni successive

Lo stato "SameSite" di un cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" corrisponde a un cookie impostato su "SameSite=None", "lax" a "SameSite=Lax" e "strict" a "SameSite=Strict". "unspecified" corrisponde a un cookie impostato senza l'attributo SameSite.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Metodi

get()

Promessa 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

Recupera le informazioni su un singolo cookie. Se per l'URL specificato esiste più di un cookie con lo stesso nome, verrà restituito quello con il percorso più lungo. Per i cookie con la stessa lunghezza del percorso, verrà restituito il cookie con la data e l'ora di creazione più antiche.

Parametri

  • dettagli

    CookieDetails

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookie?: Cookie) => void

    • biscotto

      Cookie facoltativo

      Contiene i dettagli del cookie. Questo parametro è null se non è stato trovato alcun cookie di questo tipo.

Resi

  • Promise<Cookie | undefined>

    Chrome 88 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getAll()

Promessa 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

Recupera tutti i cookie da un singolo cookie store che corrispondono alle informazioni fornite. I cookie restituiti verranno ordinati, dando la precedenza a quelli con il percorso più lungo. Se più cookie hanno la stessa lunghezza del percorso, verranno visualizzati per primi quelli con l'ora di creazione più antica. Questo metodo recupera i cookie solo per i domini per i quali l'estensione dispone delle autorizzazioni di host.

Parametri

  • dettagli

    oggetto

    Informazioni per filtrare i cookie recuperati.

    • dominio

      stringa facoltativa

      Limita i cookie recuperati a quelli i cui domini corrispondono a questo o sono sottodomini di questo.

    • nome

      stringa facoltativa

      Filtra i cookie per nome.

    • partitionKey

      CookiePartitionKey facoltativo

      Chrome 119 e versioni successive

      La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

    • percorso

      stringa facoltativa

      Limita i cookie recuperati a quelli il cui percorso corrisponde esattamente a questa stringa.

    • sicuro

      booleano facoltativo

      Filtra i cookie in base alla proprietà Secure.

    • sessione

      booleano facoltativo

      Filtra i cookie di sessione rispetto a quelli permanenti.

    • storeId

      stringa facoltativa

      L'archivio dei cookie da cui recuperare i cookie. Se omesso, verrà utilizzato il cookie store del contesto di esecuzione corrente.

    • url

      stringa facoltativa

      Limita i cookie recuperati a quelli che corrispondono all'URL specificato.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookies: Cookie[]) => void

    • cookie

      Cookie[]

      Tutti i cookie esistenti non scaduti che corrispondono alle informazioni sui cookie specificate.

Resi

  • Promise<Cookie[]>

    Chrome 88 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getAllCookieStores()

Promessa 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

Elenca tutti i cookie store esistenti.

Parametri

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Tutti i cookie store esistenti.

Resi

  • Promise<CookieStore[]>

    Chrome 88 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getPartitionKey()

Promessa In attesa
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

La chiave di partizione per il frame indicato.

Parametri

  • dettagli

    FrameDetails

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (details: object) => void

    • dettagli

      oggetto

      Contiene i dettagli sulla chiave di partizione recuperata.

      • partitionKey

        CookiePartitionKey

        La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

Resi

  • Promise<object>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

remove()

Promessa 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

Consente di eliminare un cookie in base al nome.

Parametri

  • dettagli

    CookieDetails

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (details?: object) => void

    • dettagli

      Oggetto facoltativo

      Contiene i dettagli del cookie che è stato rimosso. Se la rimozione non è riuscita per qualsiasi motivo, il valore sarà "null" e verrà impostato runtime.lastError.

      • nome

        stringa

        Il nome del cookie rimosso.

      • partitionKey

        CookiePartitionKey facoltativo

        Chrome 119 e versioni successive

        La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

      • storeId

        stringa

        L'ID del contenitore dei cookie da cui è stato rimosso il cookie.

      • url

        stringa

        L'URL associato al cookie rimosso.

Resi

  • Promise<object | undefined>

    Chrome 88 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

set()

Promessa 
chrome.cookies.set(
  details: object,
  callback?: function,
)

Imposta un cookie con i dati del cookie specificati; può sovrascrivere i cookie equivalenti, se esistono.

Parametri

  • dettagli

    oggetto

    Dettagli sul cookie impostato.

    • dominio

      stringa facoltativa

      Il dominio del cookie. Se omesso, il cookie diventa un cookie solo per l'host.

    • expirationDate

      number facoltativo

      La data di scadenza del cookie come numero di secondi dall'epoca UNIX. Se omesso, il cookie diventa un cookie di sessione.

    • httpOnly

      booleano facoltativo

      Indica se il cookie deve essere contrassegnato come HttpOnly. Il valore predefinito è false.

    • nome

      stringa facoltativa

      Il nome del cookie. Vuoto per impostazione predefinita se omesso.

    • partitionKey

      CookiePartitionKey facoltativo

      Chrome 119 e versioni successive

      La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

    • percorso

      stringa facoltativa

      Il percorso del cookie. Il valore predefinito è la parte del percorso del parametro url.

    • sameSite

      SameSiteStatus facoltativo

      Chrome 51 e versioni successive

      Lo stato same-site del cookie. Il valore predefinito è "unspecified", 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 facoltativa

      L'ID del contenitore dei cookie in cui impostare il cookie. Per impostazione predefinita, il cookie viene impostato nel cookie store del contesto di esecuzione corrente.

    • url

      stringa

      L'URI della richiesta da associare all'impostazione del cookie. Questo valore può influire sui valori predefiniti di dominio e percorso del cookie creato. Se le autorizzazioni host per questo URL non sono specificate nel file manifest, la chiamata all'API non andrà a buon fine.

    • valore

      stringa facoltativa

      Il valore del cookie. Vuoto per impostazione predefinita se omesso.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookie?: Cookie) => void

    • biscotto

      Cookie facoltativo

      Contiene i dettagli del cookie impostato. Se l'impostazione non è andata a buon fine per qualsiasi motivo, il valore sarà "null" e verrà impostato runtime.lastError.

Resi

  • Promise<Cookie | undefined>

    Chrome 88 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

Viene attivato quando un cookie viene impostato o rimosso. Come caso speciale, tieni presente che l'aggiornamento delle proprietà di un cookie viene implementato come procedura in due fasi: il cookie da aggiornare viene prima rimosso completamente, generando una notifica con "cause" di "overwrite" . Successivamente, 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

      • Il motivo alla base della modifica del cookie.

      • biscotto

        Cookie

        Informazioni sul cookie impostato o rimosso.

      • rimosso

        booleano

        True se un cookie è stato rimosso.