chrome.cookies

Opis

Użyj interfejsu API chrome.cookies, aby wysyłać zapytania o pliki cookie i je modyfikować oraz otrzymywać powiadomienia o ich zmianach.

Uprawnienia

cookies

Aby korzystać z interfejsu API plików cookie, w pliku manifestu zadeklaruj uprawnienie "cookies" oraz uprawnienia hosta dla wszystkich hostów, których pliki cookie chcesz odczytywać. Na przykład:

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

Partycjonowanie

Pliki cookie podzielone na części umożliwiają witrynie oznaczenie niektórych plików cookie jako kluczy względem źródła ramki najwyższego poziomu. Oznacza to, że jeśli np. witryna A jest umieszczona w witrynie B i witrynie C za pomocą elementu iframe, wersje wbudowanego 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 plikach cookie bez partycji. 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. Inne przykłady i informacje o wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

Typy

Reprezentuje 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 dotyczy plików cookie sesji.

  • hostOnly

    wartość logiczna

    Wartość „prawda”, jeśli plik cookie jest plikiem cookie tylko dla hosta (czyli host żądania musi dokładnie pasować do domeny pliku cookie).

  • httpOnly

    wartość logiczna

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

  • nazwa

    ciąg znaków

    Nazwa pliku cookie.

  • partitionKey

    CookiePartitionKey opcjonalnie

    Chrome w wersji 119 lub nowszej

    Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

  • ścieżka

    ciąg znaków

    Ścieżka do pliku cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 lub nowszy

    Stan pliku cookie w ramach witryny (czyli czy jest on wysyłany z żądaniami z innych witryn).

  • Bezpieczny

    wartość logiczna

    Wartość True (prawda), jeśli plik cookie jest oznaczony jako bezpieczny (czyli jego zakres jest ograniczony do bezpiecznych kanałów, zazwyczaj HTTPS).

  • sesja

    wartość logiczna

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

  • storeId

    ciąg znaków

    Identyfikator magazynu plików cookie zawierającego ten plik cookie, podany w getAllCookieStores().

  • wartość

    ciąg znaków

    Wartość pliku cookie.

CookieDetails

Chrome 88 lub nowszy

Szczegóły umożliwiające identyfikację pliku cookie.

Właściwości

  • nazwa

    ciąg znaków

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

  • partitionKey

    CookiePartitionKey opcjonalnie

    Chrome w wersji 119 lub nowszej

    Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

  • storeId

    ciąg znaków opcjonalny

    Identyfikator magazynu plików 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 jest powiązany plik cookie. Ten argument może być pełnym adresem URL, w którym przypadku wszystkie dane po ścieżce adresu URL (np. ciąg zapytania) są po prostu ignorowane. Jeśli w pliku manifestu nie ma uprawnień hosta dla tego adresu URL, wywołanie interfejsu API zakończy się niepowodzeniem.

CookiePartitionKey

Chrome w wersji 119 lub nowszej

Reprezentuje klucz partycji oddzielonego pliku cookie.

Właściwości

  • hasCrossSiteAncestor

    logiczna opcjonalna

    Chrome 130+

    Wskazuje, czy plik cookie został ustawiony w kontekście wielu witryn. Zapobiega to dostępowi witryny najwyższego poziomu umieszczonej w kontekście innych stron do plików cookie ustawionych przez witrynę najwyższego poziomu w kontekście tej samej strony.

  • topLevelSite

    ciąg znaków 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 w trybie incognito używa osobnego magazynu plików cookie niż okno bez trybu incognito.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator magazynu plików cookie.

  • tabIds

    number[]

    Identyfikatory wszystkich kart przeglądarki, które współdzielą to miejsce na pliki cookie.

FrameDetails

Oczekuje

Szczegóły umożliwiające identyfikację kadru.

Właściwości

  • documentId

    ciąg znaków opcjonalny

    Unikalny identyfikator dokumentu. Jeśli podano identyfikator ramki lub karty, 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

Podstawowy powód zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty za pomocą wywołania funkcji „chrome.cookies.remove”, „cause” będzie równe „explicit”. Jeśli plik cookie został automatycznie usunięty z powodu wygaśnięcia, „cause” będzie miał wartość „expired” (wygaśniete). Jeśli plik cookie został usunięty z powodu zastąpienia go plikiem z datą wygaśnięcia, która już minęła, parametr „cause” zostanie ustawiony na „expired_overwrite”. Jeśli plik cookie został automatycznie usunięty z powodu usuwania zbędących zasobów, „cause” zostanie „usunięty”. Jeśli plik cookie został automatycznie usunięty z powodu wywołania „set”, które go zastąpiło, „cause” będzie równe „overwrite” (zastąpiono). Odpowiednio zaplanuj swoją odpowiedź.

Typ wyliczeniowy

„evicted”

"expired"

"explicit"

"expired_overwrite"

„zapisz na dysku”

SameSiteStatus

Chrome 51 lub nowszy

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

Typ wyliczeniowy

"no_restriction"

„lax”

„strict”

„nieokreślony”

Metody

get()

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

Pobiera informacje o pojedynczym pliku cookie. Jeśli w przypadku danego adresu URL istnieje więcej niż 1 plik cookie o tej samej nazwie, zwrócony zostanie plik o najdłuższej ścieżce. W przypadku plików cookie o takim samym czasie trwania ścieżki zwrócony zostanie plik cookie o najstarszym czasie utworzenia.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (cookie?: Cookie) => void

    • ciastko

      Plik cookie opcjonalny

      Zawiera szczegółowe informacje o pliku cookie. Ten parametr ma wartość null, jeśli nie znaleziono takiego pliku cookie.

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getAll()

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

Pobiera wszystkie pliki cookie z pojedynczego magazynu plików cookie, które pasują do podanych informacji. Zwracane pliki cookie zostaną posortowane, a pierwsze będą te o najdłuższej ścieżce. Jeśli kilka plików cookie ma taką samą długość ścieżki, jako pierwsze zostaną wybrane te, które zostały utworzone najwcześniej. Ta metoda pobiera pliki cookie tylko z domen, do których rozszerzenie ma uprawnienia hosta.

Parametry

  • szczegóły

    Obiekt

    Informacje do filtrowania pobieranych plików cookie.

    • domena

      ciąg znaków opcjonalny

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

    • nazwa

      ciąg znaków opcjonalny

      Filtruje pliki cookie według nazwy.

    • partitionKey

      CookiePartitionKey opcjonalnie

      Chrome w wersji 119 lub nowszej

      Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

    • ścieżka

      ciąg znaków opcjonalny

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

    • Bezpieczny

      logiczna opcjonalna

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

    • sesja

      logiczna opcjonalna

      Filtruje pliki cookie sesji i stałe.

    • storeId

      ciąg znaków opcjonalny

      Sklep z plikami cookie, z którego mają być pobierane pliki cookie. Jeśli ominięte, zostanie użyte repozytorium plików cookie bieżącego kontekstu wykonania.

    • URL

      ciąg znaków opcjonalny

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

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (cookies: Cookie[]) => void

    • ciastka

      Cookie[]

      Wszystkie istniejące, niewygasłe pliki cookie, które pasują do podanych informacji o pliku cookie.

Zwroty

  • Obietnica<Cookie[]>

    Chrome 88 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getAllCookieStores()

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

Wyświetla listę wszystkich istniejących magazynów plików cookie.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      wszystkie istniejące magazyny plików cookie;

Zwroty

  • Promise<CookieStore[]>

    Chrome 88 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getPartitionKey()

Obietnica Oczekuje
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

Klucz partycji dla wskazanej klatki.

Parametry

  • szczegóły

    FrameDetails

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (details: object) => void

    • szczegóły

      Obiekt

      Zawiera informacje o kluczu partycji, który został pobrany.

      • partitionKey

        CookiePartitionKey

        Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

Zwroty

  • Obietkw<object>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

remove()

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

Usuwa plik cookie według nazwy.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (details?: object) => void

    • szczegóły

      object opcjonalne

      Zawiera szczegółowe informacje o usuniętym pliku cookie. Jeśli usunięcie nie powiodło się z jakiegoś powodu, wartość będzie wynosić „null”, a parametr runtime.lastError zostanie ustawiony.

      • nazwa

        ciąg znaków

        Nazwa pliku cookie, który został usunięty.

      • partitionKey

        CookiePartitionKey opcjonalnie

        Chrome w wersji 119 lub nowszej

        Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

      • storeId

        ciąg znaków

        Identyfikator magazynu plików cookie, z którego plik cookie został usunięty.

      • URL

        ciąg znaków

        Adres URL powiązany z usuniętym plikiem cookie.

Zwroty

  • Obiet<object | undefined>

    Chrome 88 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

set()

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

Ustawia plik cookie z danymi; może zastąpić istniejące pliki cookie o takich samych danych.

Parametry

  • szczegóły

    Obiekt

    Szczegóły dotyczące ustawianego pliku cookie.

    • domena

      ciąg znaków opcjonalny

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

    • expirationDate

      number opcjonalny

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

    • httpOnly

      logiczna opcjonalna

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

    • nazwa

      ciąg znaków opcjonalny

      Nazwa pliku cookie. Domyślnie puste, jeśli pominięto.

    • partitionKey

      CookiePartitionKey opcjonalnie

      Chrome w wersji 119 lub nowszej

      Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

    • ścieżka

      ciąg znaków opcjonalny

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

    • sameSite

      SameSiteStatus opcjonalne

      Chrome 51 lub nowszy

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

    • Bezpieczny

      logiczna opcjonalna

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

    • storeId

      ciąg znaków opcjonalny

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

    • URL

      ciąg znaków

      Identyfikator URI żądania do powiązania 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 ma uprawnień hosta dla tego adresu URL, wywołanie interfejsu API zakończy się niepowodzeniem.

    • wartość

      ciąg znaków opcjonalny

      Wartość pliku cookie. Domyślnie puste, jeśli pominięto.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (cookie?: Cookie) => void

    • ciastko

      Plik cookie opcjonalny

      Zawiera szczegółowe informacje o ustawionym pliku cookie. Jeśli ustawienie nie powiedzie się z jakiegokolwiek powodu, będzie ono miało wartość „null” i będzie ustawiona wartość runtime.lastError.

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onChanged

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

Wywoływane, gdy plik cookie zostanie ustawiony lub usunięty. W szczególnym przypadku aktualizacja właściwości pliku cookie jest realizowana w 2 etapów: najpierw plik cookie, który ma zostać zaktualizowany, jest całkowicie usuwany, a następnie generowane jest powiadomienie z wartością „cause” (przyczyna) „overwrite” (zastąpienie). Następnie zapisywany jest nowy plik cookie z aktualnymi wartościami, co powoduje wygenerowanie drugiego powiadomienia z wartością „cause” „explicit”.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (changeInfo: object) => void

    • changeInfo

      Obiekt

      • przyczyna

        OnChangedCause

        Podstawowy powód zmiany pliku cookie.

      • ciastko

        Plik cookie

        informacje o pliku cookie, który został ustawiony lub usunięty;

      • usunięto

        wartość logiczna

        Prawda, jeśli plik cookie został usunięty.