browser.cookies

Описание

Используйте chrome.cookies API, чтобы запрашивать и изменять файлы cookie, а также получать уведомления об их изменении.

Разрешения

cookies

Чтобы использовать API файлов cookie, объявите разрешение "cookies" в манифесте вместе с разрешениями хоста для всех хостов, к файлам cookie которых вы хотите получить доступ. Пример:

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

Сегментация товаров

Файлы cookie с разделением позволяют сайту помечать определенные файлы cookie, чтобы они сопоставлялись с источником фрейма верхнего уровня. Это означает, что если сайт A встроен с помощью iframe в сайты B и C, то встроенные версии файла cookie с разделением с сайта A могут иметь разные значения на сайтах B и C.

По умолчанию все методы API работают с неразделенными файлами cookie. Чтобы изменить это поведение, используйте свойство partitionKey.

Подробную информацию о том, как секционирование влияет на расширения, можно найти в статье Хранилище и файлы cookie.

Примеры

Простой пример использования Cookies API можно найти в каталоге examples/api/cookies. Другие примеры и инструкции по просмотру исходного кода можно найти в разделе Примеры.

Типы

Представляет информацию о файле cookie HTTP.

Свойства

  • домен

    string

    Домен файла cookie (например, www.google.com, example.com).

  • expirationDate

    number (необязательно)

    Срок действия файла cookie, выраженный в секундах, прошедших с начала эпохи UNIX. Не указывается для файлов cookie сеанса.

  • hostOnly

    Логическое значение

    True, если файл cookie предназначен только для хоста (т.е. хост запроса должен точно соответствовать домену файла cookie).

  • httpOnly

    Логическое значение

    True, если файл cookie помечен как HttpOnly (т.е. недоступен для клиентских скриптов).

  • name

    string

    Название файла cookie.

  • partitionKey

    CookiePartitionKey необязательный

    Chrome 119 и более поздние версии browser.* начиная с Chrome 148

    Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

  • путь

    string

    Путь к файлу cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 и более поздних версий browser.* начиная с Chrome 148

    Статус файла cookie в собственном контексте (т.е. отправляется ли он с межсайтовыми запросами).

  • безопасно

    Логическое значение

    True, если файл cookie помечен как безопасный (т.е. его область действия ограничена защищенными каналами, обычно HTTPS).

  • сеанс

    Логическое значение

    Возвращает значение "истина", если файл cookie является файлом cookie сеанса, а не постоянным файлом cookie с датой окончания срока действия.

  • storeId

    string

    Идентификатор хранилища файлов cookie, содержащего этот файл cookie, как указано в getAllCookieStores().

  • value

    string

    Значение файла cookie.

CookieDetails

Chrome 88+ browser.* начиная с Chrome 148

Сведения, позволяющие идентифицировать файл cookie.

Свойства

  • name

    string

    Название файла cookie, к которому нужно получить доступ.

  • partitionKey

    CookiePartitionKey необязательно

    Chrome 119 и более поздние версии browser.* начиная с Chrome 148

    Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

  • storeId

    Строка (необязательно)

    Идентификатор хранилища файлов cookie, в котором нужно искать файл cookie. По умолчанию будет использоваться хранилище файлов cookie текущего контекста выполнения.

  • url

    string

    URL, с которым связан файл cookie. В качестве аргумента можно указать полный URL. В этом случае все данные, следующие за путем URL (например, строка запроса), будут игнорироваться. Если разрешения хоста для этого URL не указаны в файле манифеста, вызов API завершится ошибкой.

CookiePartitionKey

Chrome 119 и более поздние версии browser.* начиная с Chrome 148

Представляет ключ раздела файла cookie с разделением.

Свойства

  • hasCrossSiteAncestor

    Логическое значение (необязательно)

    Chrome 130+ browser.* начиная с Chrome 148

    Указывает, был ли файл cookie задан в контексте нескольких сайтов. Это не позволяет сайту верхнего уровня, встроенному в межсайтовый контекст, получать доступ к файлам cookie, заданным сайтом верхнего уровня в контексте одного сайта.

  • topLevelSite

    Строка (необязательно)

    Сайт верхнего уровня, на котором доступен файл cookie с разделением.

CookieStore

Представляет хранилище файлов cookie в браузере. Например, в окне инкогнито используется отдельное хранилище файлов cookie, не связанное с обычным окном.

Свойства

  • id

    string

    Уникальный идентификатор хранилища файлов cookie.

  • tabIds

    number[]

    Идентификаторы всех вкладок браузера, которые используют это хранилище файлов cookie.

FrameDetails

Chrome 132+ browser.* начиная с Chrome 148

Сведения, позволяющие идентифицировать фрейм.

Свойства

  • documentId

    Строка (необязательно)

    Уникальный идентификатор документа. Если указаны frameId и/или tabId, они будут проверены на соответствие документу, найденному по указанному идентификатору документа.

  • frameId

    number (необязательно)

    Уникальный идентификатор фрейма на вкладке.

  • tabId

    number (необязательно)

    Уникальный идентификатор вкладки, содержащей фрейм.

OnChangedCause

Chrome 44+ browser.* начиная с Chrome 148

Причина изменения файла cookie. Если файл cookie был вставлен или удален с помощью явного вызова chrome.cookies.remove, значением cause будет explicit. Если файл cookie был автоматически удален по истечении срока действия, в поле "cause" будет указано "expired". Если файл cookie был удален из-за перезаписи с уже истекшим сроком действия, для параметра cause будет установлено значение expired_overwrite. Если файл cookie был автоматически удален в результате сборки мусора, "cause" будет "evicted". Если файл cookie был автоматически удален из-за вызова set, который его перезаписал, в поле cause будет указано значение overwrite. Учитывайте это при планировании.

Перечисление

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 и более поздних версий browser.* начиная с Chrome 148

Состояние SameSite файла cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). Значение no_restriction соответствует файлу cookie с атрибутом SameSite=None, lax – SameSite=Lax, а strict – SameSite=Strict. Значение unspecified соответствует файлу cookie, для которого не задан атрибут SameSite.

Перечисление

"no_restriction"

"lax"

"strict"

"unspecified"

Методы

get()

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

Извлекает информацию об одном файле cookie. Если для указанного URL существует несколько файлов cookie с одинаковым названием, будет возвращен файл с самым длинным путем. Если у файлов cookie одинаковая длина пути, будет возвращен файл, созданный раньше.

Параметры

Возвраты

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* начиная с Chrome 148

getAll()

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

Извлекает из одного хранилища файлов cookie все файлы cookie, соответствующие заданной информации. Возвращенные файлы cookie будут отсортированы, причем первыми будут файлы с самым длинным путем. Если у нескольких файлов cookie длина пути одинакова, то первыми будут показаны те, которые были созданы раньше. Этот метод извлекает файлы cookie только для доменов, на которые у расширения есть разрешения хоста.

Параметры

  • подробные сведения

    Объект

    Информация для фильтрации извлекаемых файлов cookie.

    • домен

      Строка (необязательно)

      Ограничивает извлекаемые файлы cookie теми, домены которых совпадают с указанным или являются его субдоменами.

    • name

      Строка (необязательно)

      Фильтрация файлов cookie по названию.

    • partitionKey

      CookiePartitionKey необязательно

      Chrome 119 и более поздних версий browser.* начиная с Chrome 148

      Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

    • путь

      Строка (необязательно)

      Ограничивает извлекаемые файлы cookie теми, путь к которым точно соответствует этой строке.

    • безопасно

      Логическое значение (необязательно)

      Фильтрует файлы cookie по свойству Secure.

    • сеанс

      Логическое значение (необязательно)

      Позволяет отфильтровать файлы cookie сеанса и постоянные файлы cookie.

    • storeId

      Строка (необязательно)

      Хранилище, из которого нужно получить файлы cookie. Если не указано, будет использоваться хранилище файлов cookie текущего контекста выполнения.

    • url

      Строка (необязательно)

      Ограничивает извлеченные файлы cookie теми, которые соответствуют указанному URL.

Возвраты

  • Promise<Cookie[]>

    Chrome 88+ browser.* начиная с Chrome 148

getAllCookieStores()

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

Список всех существующих хранилищ файлов cookie.

Возвраты

  • Promise<CookieStore[]>

    Chrome 88+ browser.* начиная с Chrome 148

getPartitionKey()

Chrome 132+ browser.* начиная с Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Ключ раздела для указанного фрейма.

Параметры

Возвраты

  • Promise<object>

remove()

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

Удаляет файл cookie по имени.

Параметры

Возвраты

  • Promise<object | undefined>

    Chrome 88+ browser.* начиная с Chrome 148

set()

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

Создает файл cookie с указанными данными. При этом могут быть перезаписаны существующие файлы cookie.

Параметры

  • подробные сведения

    Объект

    Сведения о файле cookie, который устанавливается.

    • домен

      Строка (необязательно)

      Домен файла cookie. Если этот атрибут не указан, файл cookie будет доступен только для хоста.

    • expirationDate

      number (необязательно)

      Срок действия файла cookie, выраженный в секундах, прошедших с начала эпохи UNIX. Если этот параметр не указан, файл cookie становится файлом cookie сеанса.

    • httpOnly

      Логическое значение (необязательно)

      Должен ли файл cookie быть помечен как HttpOnly. Значение по умолчанию – false.

    • name

      Строка (необязательно)

      Название файла cookie. Если не указано, по умолчанию поле остается пустым.

    • partitionKey

      CookiePartitionKey необязательно

      Chrome 119 и более поздние версии browser.* начиная с Chrome 148

      Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

    • путь

      Строка (необязательно)

      Путь к файлу cookie. По умолчанию используется часть пути параметра URL.

    • sameSite

      SameSiteStatus необязательный

      Chrome 51 и более поздних версий browser.* начиная с Chrome 148

      Статус файла cookie для одного сайта. Если значение не указано, по умолчанию используется "unspecified", то есть файл cookie устанавливается без атрибута SameSite.

    • безопасно

      Логическое значение (необязательно)

      Указывает, должен ли файл cookie быть помечен как безопасный. Значение по умолчанию – false.

    • storeId

      Строка (необязательно)

      Идентификатор хранилища файлов cookie, в котором нужно задать файл cookie. По умолчанию файл cookie устанавливается в хранилище файлов cookie текущего контекста выполнения.

    • url

      string

      URI запроса, который нужно связать с настройкой файла cookie. Это значение может повлиять на домен и путь по умолчанию для созданного файла cookie. Если разрешения хоста для этого URL не указаны в файле манифеста, вызов API завершится ошибкой.

    • value

      Строка (необязательно)

      Значение файла cookie. Если не указано, по умолчанию поле остается пустым.

Возвраты

  • Promise<Cookie | undefined>

    Chrome 88+ browser.* начиная с Chrome 148

События

onChanged

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

Срабатывает, когда файл cookie устанавливается или удаляется. Обратите внимание, что обновление свойств файла cookie выполняется в два этапа: сначала файл cookie, который нужно обновить, полностью удаляется, в результате чего генерируется уведомление с причиной "overwrite" . После этого записывается новый файл cookie с обновленными значениями, что приводит к созданию второго уведомления с причиной "explicit".

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

    (changeInfo: object) => void

    • changeInfo

      Объект

      • Причина изменения файла cookie.

      • печенье

        Файл cookie

        Информация о файле cookie, который был создан или удален.

      • удалено

        Логическое значение

        True, если файл cookie был удален.