browser.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 używać interfejsu API plików cookie, zadeklaruj w pliku manifestu uprawnienie "cookies" oraz uprawnienia 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ć powiązane z miejscem pochodzenia ramki najwyższego poziomu. Oznacza to, że jeśli np. witryna A jest umieszczona w witrynie B i witrynie C za pomocą elementu iframe, umieszczone wersje oddzielonego 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 Pamięć i pliki cookie.

Przykłady

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

Typy

Reprezentuje informacje o pliku cookie HTTP.

Właściwości

  • domena

    tekst

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

  • expirationDate

    number optional

    Data ważności pliku cookie jako liczba sekund od początku epoki uniksowej. Nie jest podawany w przypadku plików cookie sesji.

  • hostOnly

    wartość logiczna

    Wartość „true”, jeśli plik cookie jest plikiem cookie tylko dla hosta (tzn. host żądania musi dokładnie odpowiadać domenie pliku cookie).

  • httpOnly

    wartość logiczna

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

  • nazwa

    tekst

    Nazwa pliku cookie.

  • partitionKey

    CookiePartitionKey opcjonalne

    Chrome 119 lub nowsza browser.* od Chrome 148

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

  • ścieżka

    tekst

    Ścieżka pliku cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 lub nowsza browser.* od Chrome 148

    Stan pliku cookie w tej samej witrynie (czyli czy plik cookie jest wysyłany z żądaniami z innej witryny).

  • 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

    tekst

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

  • wartość

    tekst

    Wartość pliku cookie.

CookieDetails

Chrome 88 lub nowsza browser.* od Chrome 148

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

Właściwości

  • nazwa

    tekst

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

  • partitionKey

    CookiePartitionKey opcjonalne

    Chrome 119 lub nowsza browser.* od Chrome 148

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

  • storeId

    ciąg znaków opcjonalny

    Identyfikator magazynu plików cookie, w którym ma być wyszukiwany plik cookie. Domyślnie używany jest magazyn plików cookie bieżącego kontekstu wykonywania.

  • URL

    tekst

    Adres URL, z którym jest powiązany plik cookie, do którego chcesz uzyskać dostęp. Ten argument może być pełnym adresem URL.W takim przypadku wszystkie dane 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 browser.* od Chrome 148

Reprezentuje klucz partycji oddzielonego pliku cookie.

Właściwości

  • hasCrossSiteAncestor

    boolean opcjonalne

    Chrome 130 lub nowsza browser.* od Chrome 148

    Wskazuje, czy plik cookie został ustawiony w kontekście wielu witryn. Uniemożliwia to witrynie najwyższego poziomu osadzonej w kontekście innych stron dostęp 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 jest dostępny 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 trybu standardowego.

Właściwości

  • id

    tekst

    Unikalny identyfikator magazynu plików cookie.

  • tabIds

    number[]

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

FrameDetails

Chrome 132 lub nowsza browser.* od Chrome 148

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

Właściwości

  • documentId

    ciąg znaków opcjonalny

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

  • frameId

    number optional

    Unikalny identyfikator ramki na karcie.

  • tabId

    number optional

    Unikalny identyfikator karty zawierającej ramkę.

OnChangedCause

Chrome 44 lub nowsza browser.* od Chrome 148

Przyczyna zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty przez jawne wywołanie „chrome.cookies.remove”, „cause” będzie mieć wartość „explicit”. Jeśli plik cookie został automatycznie usunięty z powodu wygaśnięcia, „przyczyna” będzie miała wartość „wygaśnięcie”. Jeśli plik cookie został usunięty, ponieważ został zastąpiony plikiem z datą ważności, która już minęła, „przyczyna” zostanie ustawiona na „expired_overwrite”. Jeśli plik cookie został automatycznie usunięty w ramach czyszczenia 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”. Zaplanuj odpowiednio swoje działania.

Typ wyliczeniowy

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 lub nowsza browser.* od Chrome 148

Stan „SameSite” pliku cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). Wartość „no_restriction” odpowiada plikowi cookie z ustawieniem „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()

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

Pobiera informacje o pojedynczym pliku cookie. Jeśli dla danego adresu URL istnieje więcej niż 1 plik cookie o tej samej nazwie, zostanie zwrócony ten z najdłuższą ścieżką. W przypadku plików cookie o tej samej długości ścieżki zwracany jest plik cookie z najwcześniejszym czasem utworzenia.

Parametry

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 lub nowsza browser.* od Chrome 148

getAll()

browser.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 zostaną posortowane, przy czym te z najdłuższą ścieżką będą na początku. Jeśli kilka plików cookie ma tę samą długość ścieżki, pierwszeństwo będą miały te z najwcześniejszym czasem utworzenia. 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

      ciąg znaków opcjonalny

      Ogranicza pobierane 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 opcjonalne

      Chrome 119 lub nowsza browser.* od Chrome 148

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

    • ścieżka

      ciąg znaków opcjonalny

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

    • Bezpieczny

      boolean opcjonalne

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

    • sesja

      boolean opcjonalne

      Odfiltrowuje pliki cookie sesji i trwałe pliki cookie.

    • storeId

      ciąg znaków opcjonalny

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

    • URL

      ciąg znaków opcjonalny

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

Zwroty

  • Promise<Cookie[]>

    Chrome 88 lub nowsza browser.* od Chrome 148

getAllCookieStores()

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

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

Zwroty

  • Promise<CookieStore[]>

    Chrome 88 lub nowsza browser.* od Chrome 148

getPartitionKey()

Chrome 132 lub nowsza browser.* od Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Klucz partycji dla wskazanej ramki.

Parametry

Zwroty

  • Promise<object>

remove()

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

Usuwa plik cookie według nazwy.

Parametry

Zwroty

  • Promise<object | undefined>

    Chrome 88 lub nowsza browser.* od Chrome 148

set()

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

Konfiguruje plik cookie z podanymi danymi. Może zastąpić odpowiednie pliki cookie, jeśli istnieją.

Parametry

  • szczegóły

    obiekt

    Szczegółowe informacje o ustawianym pliku cookie.

    • domena

      ciąg znaków opcjonalny

      Domena pliku cookie. Jeśli go pominiesz, plik cookie stanie się plikiem cookie hosta.

    • expirationDate

      number optional

      Data ważności pliku cookie jako liczba sekund od początku epoki uniksowej. Jeśli go pominiesz, plik cookie stanie się plikiem cookie sesji.

    • httpOnly

      boolean opcjonalne

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

    • nazwa

      ciąg znaków opcjonalny

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

    • partitionKey

      CookiePartitionKey opcjonalne

      Chrome 119 lub nowsza browser.* od Chrome 148

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

    • ścieżka

      ciąg znaków opcjonalny

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

    • sameSite

      SameSiteStatus opcjonalny

      Chrome 51 lub nowsza browser.* od Chrome 148

      Stan pliku cookie w kontekście tej samej strony. Domyślna wartość to „unspecified” (nieokreślona), czyli jeśli zostanie pominięta, plik cookie zostanie ustawiony bez określania atrybutu SameSite.

    • Bezpieczny

      boolean opcjonalne

      Określa, czy plik cookie powinien 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 wykonywania.

    • URL

      tekst

      Identyfikator URI żądania, który ma zostać powiązany z ustawieniem pliku cookie. Ta wartość może mieć wpływ 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ść

      ciąg znaków opcjonalny

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

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 lub nowsza browser.* od Chrome 148

Wydarzenia

onChanged

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

Uruchamiane, gdy plik cookie jest ustawiany lub usuwany. W szczególnym przypadku aktualizowanie właściwości pliku cookie jest realizowane w ramach 2-etapowego procesu: plik cookie, który ma zostać zaktualizowany, jest najpierw całkowicie usuwany, co powoduje wygenerowanie powiadomienia z „przyczyną” „zastąpienia”. Następnie zapisywany jest nowy plik cookie ze zaktualizowanymi wartościami, co powoduje wygenerowanie drugiego powiadomienia z przyczyną „explicit”.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (changeInfo: object) => void

    • changeInfo

      obiekt

      • przyczyna

        OnChangedCause

        Przyczyna zmiany pliku cookie.

      • ciastko

        Plik cookie

        Informacje o pliku cookie, który został ustawiony lub usunięty.

      • usunięto

        wartość logiczna

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