chrome.cookies

Opis

Używaj interfejsu chrome.cookies API do wysyłania zapytań dotyczących plików cookie i ich modyfikowania oraz do otrzymywania powiadomień o ich zmianach.

Uprawnienia

cookies

Aby używać interfejsu API plików cookie, zadeklaruj w pliku manifestu uprawnienie "cookies" wraz z uprawnieniami hosta dla wszystkich hostów, do których plików cookie chcesz mieć dostęp. Na przykład:

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

Partycjonowanie

Oddzielone pliki cookie umożliwiają witrynie oznaczenie, że niektóre pliki cookie powinny być kluczowane względem pochodzenia ramki najwyższego poziomu. Oznacza to, że jeśli np. witryna A jest umieszczona w ramce iframe w witrynach B i C, umieszczone wersje podzielonego pliku cookie z witryny A mogą mieć różne wartości w witrynach B i C.

Domyślnie wszystkie metody interfejsu API działają na niepodzielonych plikach cookie. Aby zastąpić to działanie, możesz użyć właściwości partitionKey.

Szczegółowe informacje o ogólnym wpływie partycjonowania na rozszerzenia znajdziesz w artykule Miejsce na dane i pliki cookie.

Przykłady

Prosty przykład użycia interfejsu Cookies API znajdziesz w katalogu examples/api/cookies. Więcej przykładów i pomoc w wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

Typy

Zawiera informacje o pliku cookie HTTP.

Właściwości

  • domena

    ciąg znaków

    Domena pliku cookie (np. „www.google.com”, „example.com”).

  • expirationDate

    number opcjonalny

    Data wygaśnięcia pliku cookie podana jako liczba sekund od początku czasu uniksowego. Nie jest podawany w przypadku plików cookie sesji.

  • hostOnly

    Wartość logiczna

    Wartość „prawda”, jeśli plik cookie jest plikiem cookie tylko dla hosta (tzn. host żądania musi być dokładnie zgodny z domeną pliku cookie).

  • httpOnly

    Wartość logiczna

    Wartość Prawda, jeśli plik cookie jest oznaczony jako HttpOnly (tzn. jest niedostępny dla skryptów po stronie klienta).

  • nazwa

    ciąg znaków

    Nazwa pliku cookie.

  • partitionKey

    CookiePartitionKey opcjonalny

    Chrome 119 lub nowsza

    Klucz partycji do odczytywania lub modyfikowania plików cookie z atrybutem Partitioned.

  • ścieżka

    ciąg znaków

    Ścieżka pliku cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 lub nowsza

    Stan pliku cookie w odniesieniu do tej samej witryny (czyli czy plik cookie jest wysyłany w przypadku żądań z innych witryn).

  • Bezpieczny

    Wartość logiczna

    Wartość „true”, jeśli plik cookie jest oznaczony jako bezpieczny (tzn. jego zakres jest ograniczony do bezpiecznych kanałów, zwykle HTTPS).

  • sesja

    Wartość logiczna

    Wartość „prawda”, jeśli plik cookie jest plikiem cookie sesji, a nie trwałym plikiem cookie z datą ważności.

  • storeId

    ciąg znaków

    Identyfikator sklepu z plikami cookie zawierającego ten plik cookie, podany w funkcji getAllCookieStores().

  • wartość

    ciąg znaków

    Wartość pliku cookie.

CookieDetails

Chrome 88 lub nowsza

Szczegóły identyfikujące plik cookie.

Właściwości

  • nazwa

    ciąg znaków

    Nazwa pliku cookie, do którego chcesz uzyskać dostęp.

  • partitionKey

    CookiePartitionKey opcjonalny

    Chrome 119 lub nowsza

    Klucz partycji do odczytywania lub modyfikowania plików cookie z atrybutem Partitioned.

  • storeId

    string opcjonalny

    Identyfikator sklepu z plikami cookie, w którym należy szukać pliku cookie. Domyślnie używany jest magazyn plików cookie bieżącego kontekstu wykonania.

  • URL

    ciąg znaków

    Adres URL, z którym powiązany jest plik cookie, do którego chcesz uzyskać dostęp. Ten argument może być pełnym adresem URL.W takim przypadku wszystkie dane znajdujące się po ścieżce adresu URL (np. ciąg zapytania) są po prostu ignorowane. Jeśli w pliku manifestu nie określono uprawnień hosta dla tego adresu URL, wywołanie interfejsu API zakończy się niepowodzeniem.

CookiePartitionKey

Chrome 119 lub nowsza

Reprezentuje klucz partycji oddzielonego pliku cookie.

Właściwości

  • hasCrossSiteAncestor

    wartość logiczna opcjonalna

    Chrome 130 lub nowsza

    Wskazuje, czy plik cookie został ustawiony w kontekście obejmującym wiele witryn. Zapobiega to dostępowi witryny najwyższego poziomu osadzonej w kontekście innej witryny do plików cookie ustawionych przez witrynę najwyższego poziomu w kontekście tej samej witryny.

  • topLevelSite

    string opcjonalny

    Witryna najwyższego poziomu, w której dostępny jest oddzielony plik cookie.

CookieStore

Reprezentuje magazyn plików cookie w przeglądarce. Na przykład okno trybu incognito używa innego magazynu plików cookie niż okno w trybie zwykłym.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator sklepu z plikami cookie.

  • tabIds

    number[]

    Identyfikatory wszystkich kart przeglądarki, które współdzielą ten magazyn plików cookie.

FrameDetails

Chrome 132 lub nowsza

Szczegóły identyfikujące ramkę.

Właściwości

  • documentId

    string opcjonalny

    Unikalny identyfikator dokumentu. Jeśli podano frameId lub tabId, zostaną one zweryfikowane pod kątem zgodności z dokumentem znalezionym na podstawie podanego identyfikatora dokumentu.

  • frameId

    number opcjonalny

    Unikalny identyfikator ramki na karcie.

  • tabId

    number opcjonalny

    Unikalny identyfikator karty zawierającej ramkę.

OnChangedCause

Chrome 44 lub nowszy

Przyczyna zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty w wyniku jawnego wywołania funkcji „chrome.cookies.remove”, wartość parametru „cause” będzie wynosić „explicit”. Jeśli plik cookie został automatycznie usunięty z powodu wygaśnięcia, „przyczyna” będzie miała wartość „expired” (wygasł). Jeśli plik cookie został usunięty, ponieważ został zastąpiony plikiem z datą ważności, która już wygasła, „cause” (przyczyna) zostanie ustawiona na „expired_overwrite”. Jeśli plik cookie został automatycznie usunięty z powodu odzyskiwania pamięci, „przyczyna” będzie miała wartość „evicted”. Jeśli plik cookie został automatycznie usunięty z powodu wywołania „set”, które go zastąpiło, „cause” będzie mieć wartość „overwrite”. Odpowiednio zaplanuj swoją reakcję.

Typ wyliczeniowy

„evicted”

„expired”

„explicit”

"expired_overwrite"

„overwrite”

SameSiteStatus

Chrome 51 lub nowsza

Stan atrybutu „SameSite” pliku cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). Wartość „no_restriction” odpowiada plikowi cookie ustawionemu z atrybutem „SameSite=None”, „lax” – „SameSite=Lax”, a „strict” – „SameSite=Strict”. „unspecified” odpowiada plikowi cookie ustawionemu bez atrybutu SameSite.

Typ wyliczeniowy

"no_restriction"

„lax”

„strict”

„unspecified”

Metody

get()

chrome.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

Pobiera informacje o pojedynczym pliku cookie. Jeśli dla danego adresu URL istnieje więcej niż jeden plik cookie o tej samej nazwie, zwracany jest ten o najdłuższej ścieżce. W przypadku plików cookie o tej samej długości ścieżki zwracany jest plik cookie z najwcześniejszą datą utworzenia.

Parametry

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 lub nowsza

getAll()

chrome.cookies.getAll(
  details: object,
): Promise<Cookie[]>

Pobiera wszystkie pliki cookie z pojedynczego magazynu plików cookie, które pasują do podanych informacji. Zwrócone pliki cookie będą posortowane, przy czym na początku znajdą się te o najdłuższej ścieżce. Jeśli kilka plików cookie ma taką samą długość ścieżki, pierwszeństwo mają te, które zostały utworzone najwcześniej. Ta metoda pobiera pliki cookie tylko w przypadku domen, do których rozszerzenie ma uprawnienia hosta.

Parametry

  • szczegóły

    obiekt

    Informacje do filtrowania pobieranych plików cookie.

    • domena

      string opcjonalny

      Ogranicza pobierane pliki cookie do tych, których domeny pasują do tej domeny lub są jej subdomenami.

    • nazwa

      string opcjonalny

      Filtruje pliki cookie według nazwy.

    • partitionKey

      CookiePartitionKey opcjonalny

      Chrome 119 lub nowsza

      Klucz partycji do odczytywania lub modyfikowania plików cookie z atrybutem Partitioned.

    • ścieżka

      string opcjonalny

      Ogranicza pobierane pliki cookie do tych, których ścieżka dokładnie pasuje do tego ciągu znaków.

    • Bezpieczny

      wartość logiczna opcjonalna

      Filtruje pliki cookie według właściwości Secure.

    • sesja

      wartość logiczna opcjonalna

      Filtruje pliki cookie sesji i pliki cookie trwałe.

    • storeId

      string opcjonalny

      Magazyn plików cookie, z którego mają być pobierane pliki cookie. Jeśli zostanie pominięty, użyty zostanie magazyn plików cookie bieżącego kontekstu wykonania.

    • URL

      string opcjonalny

      Ogranicza pobrane pliki cookie do tych, które pasują do podanego adresu URL.

Zwroty

  • Promise<Cookie[]>

    Chrome 88 lub nowsza

getAllCookieStores()

chrome.cookies.getAllCookieStores(): Promise<CookieStore[]>

Wyświetla listę wszystkich istniejących sklepów z plikami cookie.

Zwroty

getPartitionKey()

Chrome 132 lub nowsza 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Klucz partycji dla wskazanej klatki.

Parametry

Zwroty

  • Promise<object>

remove()

chrome.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

Usuwa plik cookie według nazwy.

Parametry

Zwroty

  • Promise<object | undefined>

    Chrome 88 lub nowsza

set()

chrome.cookies.set(
  details: object,
): Promise<Cookie | undefined>

Ustawia plik cookie z podanymi danymi. Może zastąpić równoważne pliki cookie, jeśli takie istnieją.

Parametry

  • szczegóły

    obiekt

    Szczegóły dotyczące ustawianego pliku cookie.

    • domena

      string opcjonalny

      Domena pliku cookie. Jeśli ten argument nie zostanie podany, plik cookie stanie się plikiem cookie tylko dla hosta.

    • expirationDate

      number opcjonalny

      Data wygaśnięcia pliku cookie podana jako liczba sekund od początku czasu uniksowego. Jeśli nie zostanie podana, plik cookie stanie się plikiem cookie sesji.

    • httpOnly

      wartość logiczna opcjonalna

      Określa, czy plik cookie ma być oznaczony jako HttpOnly. Wartość domyślna to fałsz.

    • nazwa

      string opcjonalny

      Nazwa pliku cookie. Jeśli zostanie pominięty, domyślnie jest pusty.

    • partitionKey

      CookiePartitionKey opcjonalny

      Chrome 119 lub nowsza

      Klucz partycji do odczytywania lub modyfikowania plików cookie z atrybutem Partitioned.

    • ścieżka

      string opcjonalny

      Ścieżka pliku cookie. Domyślnie jest to część ścieżki parametru adresu URL.

    • sameSite

      SameSiteStatus opcjonalny

      Chrome 51 lub nowsza

      Stan pliku cookie w kontekście tej samej witryny. Domyślna wartość to „unspecified” (nieokreślony), tzn. jeśli ten atrybut zostanie pominięty, plik cookie zostanie ustawiony bez określania atrybutu SameSite.

    • Bezpieczny

      wartość logiczna opcjonalna

      Określa, czy plik cookie ma być oznaczony jako bezpieczny. Wartość domyślna to fałsz.

    • storeId

      string opcjonalny

      Identyfikator magazynu plików cookie, w którym ma zostać ustawiony plik cookie. Domyślnie plik cookie jest ustawiany w pamięci plików cookie bieżącego kontekstu wykonania.

    • URL

      ciąg znaków

      Identyfikator URI żądania, który ma być powiązany z ustawieniem pliku cookie. Ta wartość może wpływać na domyślne wartości domeny i ścieżki utworzonego pliku cookie. Jeśli w pliku manifestu nie określono uprawnień hosta dla tego adresu URL, wywołanie interfejsu API zakończy się niepowodzeniem.

    • wartość

      string opcjonalny

      Wartość pliku cookie. Jeśli zostanie pominięty, domyślnie jest pusty.

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 lub nowsza

Wydarzenia

onChanged

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

Wywoływane, gdy plik cookie jest ustawiany lub usuwany. W szczególnym przypadku aktualizacja właściwości pliku cookie jest realizowana w 2 etapach: najpierw plik cookie do zaktualizowania jest całkowicie usuwany, co generuje powiadomienie z przyczyną „overwrite” (zastąpienie). Następnie zapisywany jest nowy plik cookie ze zaktualizowanymi wartościami, co generuje drugie powiadomienie z wartością „cause” ustawioną na „explicit”.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (changeInfo: object) => void

    • changeInfo

      obiekt

      • przyczyną

        OnChangedCause

        Przyczyna zmiany pliku cookie.

      • ciastko

        Plik cookie

        Informacje o ustawionym lub usuniętym pliku cookie.

      • usunięto

        Wartość logiczna

        Wartość „true”, jeśli plik cookie został usunięty.