chrome.cookies

Описание

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

Разрешения

cookies

Манифест

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

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

Разделение

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

chrome.cookies не поддерживает секционирование. Это означает, что все методы читают и записывают файлы cookie со всех разделов. Метод cookies.set() сохраняет файлы cookie в разделе по умолчанию.

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

Примеры

Вы можете найти простой пример использования API файлов cookie в каталоге example/api/cookies . Другие примеры и помощь в просмотре исходного кода см. в разделе «Примеры» .

Типы

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

Характеристики

  • домен

    нить

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

  • Дата окончания срока

    номер необязательно

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

  • только хост

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

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

  • httpOnly

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

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

  • имя

    нить

    Имя файла cookie.

  • Ключ раздела

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

    Хром 119+

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

  • путь

    нить

    Путь файла cookie.

  • Хром 51+

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

  • безопасный

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

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

  • сессия

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

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

  • идентификатор магазина

    нить

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

  • ценить

    нить

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

CookieDetails

Хром 88+

Подробности для идентификации файла cookie.

Характеристики

  • имя

    нить

    Имя файла cookie для доступа.

  • Ключ раздела

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

    Хром 119+

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

  • идентификатор магазина

    строка необязательна

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

  • URL

    нить

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

CookiePartitionKey

Хром 119+

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

Характеристики

  • hasCrossSiteAncestor

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

    Хром 130+

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

  • topLevelSite

    строка необязательна

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

CookieStore

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

Характеристики

  • идентификатор

    нить

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

  • tabIds

    число[]

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

FrameDetails

В ожидании

Детали для идентификации рамы.

Характеристики

  • идентификатор документа

    строка необязательна

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

  • идентификатор кадра

    номер необязательно

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

  • идентификатор табуляции

    номер необязательно

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

OnChangedCause

Хром 44+

Основная причина изменения файла cookie. Если файл cookie был вставлен или удален посредством явного вызова «chrome.cookies.remove», «причина» будет «явной». Если файл cookie был автоматически удален из-за истечения срока его действия, «причина» будет «истек». Если файл cookie был удален из-за перезаписи с уже истекшим сроком действия, для параметра «причина» будет установлено значение «expired_overwrite». Если файл cookie был автоматически удален из-за сборки мусора, «причина» будет «выселена». Если файл cookie был автоматически удален из-за вызова «set», который перезаписал его, «причиной» будет «перезаписать». Планируйте свой ответ соответствующим образом.

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

"выселен"

"истекший"

"явный"

"истек_перезаписать"

"перезаписать"

SameSiteStatus

Хром 51+

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

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

"без_ограничений"

"слабый"

"строгий"

"неопределенный"

Методы

get()

Обещать
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (cookie?: Cookie) => void

    • печенье

      Файл cookie необязательно

      Содержит сведения о файле cookie. Этот параметр имеет значение null, если такой файл cookie не найден.

Возврат

  • Обещание< Файл cookie | не определено>

    Хром 88+

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

getAll()

Обещать
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

Параметры

  • подробности

    объект

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

    • домен

      строка необязательна

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

    • имя

      строка необязательна

      Фильтрует файлы cookie по имени.

    • Ключ раздела

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

      Хром 119+

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

    • путь

      строка необязательна

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

    • безопасный

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

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

    • сессия

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

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

    • идентификатор магазина

      строка необязательна

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

    • URL

      строка необязательна

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

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (cookies: Cookie[]) => void

    • печенье

      Файл cookie []

      Все существующие файлы cookie с неистёкшим сроком действия, соответствующие данной информации о файлах cookie.

Возврат

  • Обещание< Cookie []>

    Хром 88+

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

getAllCookieStores()

Обещать
chrome.cookies.getAllCookieStores(
  callback?: function,
)

Перечисляет все существующие хранилища файлов cookie.

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (cookieStores: CookieStore[]) => void

Возврат

  • Обещание< CookieStore []>

    Хром 88+

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

getPartitionKey()

Ожидание обещания
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

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

Параметры

  • подробности

    Детали рамки

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (details: object) => void

    • подробности

      объект

      Содержит сведения о полученном ключе раздела.

      • Ключ раздела

        CookiePartitionKey

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

Возврат

  • Обещание<объект>

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

remove()

Обещать
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (details?: object) => void

    • подробности

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

      Содержит сведения об удаленном файле cookie. Если по какой-либо причине удаление не удалось, оно будет иметь значение «null» и будет установлен runtime.lastError .

      • имя

        нить

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

      • Ключ раздела

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

        Хром 119+

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

      • идентификатор магазина

        нить

        Идентификатор хранилища файлов cookie, из которого файл cookie был удален.

      • URL

        нить

        URL-адрес, связанный с удаленным файлом cookie.

Возврат

  • Обещание<объект | не определено>

    Хром 88+

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

set()

Обещать
chrome.cookies.set(
  details: object,
  callback?: function,
)

Устанавливает файл cookie с указанными данными файла cookie; может перезаписать эквивалентные файлы cookie, если они существуют.

Параметры

  • подробности

    объект

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

    • домен

      строка необязательна

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

    • Дата окончания срока

      номер необязательно

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

    • httpOnly

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

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

    • имя

      строка необязательна

      Имя файла cookie. По умолчанию пусто, если опущено.

    • Ключ раздела

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

      Хром 119+

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

    • путь

      строка необязательна

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

    • тот же сайт

      SameSiteStatus необязательно.

      Хром 51+

      Статус файла cookie на том же сайте. По умолчанию установлено значение «не указано», т. е. если этот параметр опущен, файл cookie устанавливается без указания атрибута SameSite.

    • безопасный

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

      Должен ли файл cookie быть помечен как безопасный. По умолчанию ложь.

    • идентификатор магазина

      строка необязательна

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

    • URL

      нить

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

    • ценить

      строка необязательна

      Значение файла cookie. По умолчанию пусто, если опущено.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    (cookie?: Cookie) => void

    • печенье

      Файл cookie необязательно

      Содержит сведения об установленном файле cookie. Если по какой-либо причине установка не удалась, это значение будет равно «null», и будет установлен runtime.lastError .

Возврат

  • Обещание< Файл cookie | не определено>

    Хром 88+

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

События

onChanged

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

Запускается, когда файл cookie устанавливается или удаляется. В качестве особого случая обратите внимание, что обновление свойств файла cookie реализуется в виде двухэтапного процесса: сначала обновляемый файл cookie полностью удаляется, при этом генерируется уведомление с «причиной» «перезаписи». После этого записывается новый файл cookie с обновленными значениями, генерируя второе уведомление с «причиной» «явно».

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

    (changeInfo: object) => void

    • изменениеИнформация

      объект

      • причина

        OnChangedCause

        Основная причина изменения файла cookie.

      • печенье

        печенье

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

      • удаленный

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

        Истинно, если файл cookie был удален.