chrome.cookies

説明

chrome.cookies API を使用して、Cookie のクエリと変更を行い、Cookie が変更されたときに通知を受け取ります。

権限

cookies

cookies API を使用するには、マニフェストで "cookies" 権限と、Cookie にアクセスするホストのホスト権限を宣言します。例:

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

パーティショニング

パーティショニングされた Cookie を使用すると、特定の Cookie をトップレベル フレームのオリジンに対してキー付けする必要があることをサイトがマークできます。たとえば、サイト A が iframe を使用してサイト B とサイト C に埋め込まれている場合、A のパーティション化された Cookie の埋め込みバージョンは、B と C で異なる値を持つことができます。

デフォルトでは、すべての API メソッドはパーティショニングされていない Cookie で動作します。partitionKey プロパティを使用すると、この動作をオーバーライドできます。

拡張機能のパーティショニングによる一般的な影響については、ストレージと Cookie をご覧ください。

例

cookies API の使用例は、examples/api/cookies ディレクトリにあります。その他の例とソースコードの表示方法については、サンプルをご覧ください。

型

HTTP Cookie に関する情報を表します。

プロパティ

  • ドメイン

    文字列

    クッキーのドメイン（例:「www.google.com」、「example.com」）。

  • expirationDate

    number（省略可）

    Cookie の有効期限（UNIX エポックからの秒数）。セッション Cookie には提供されません。

  • hostOnly

    ブール値

    Cookie がホスト専用 Cookie の場合（つまり、リクエストのホストが Cookie のドメインと完全に一致している必要がある場合）は true です。

  • httpOnly

    ブール値

    Cookie が HttpOnly としてマークされている場合（つまり、Cookie にクライアントサイド スクリプトからアクセスできない場合）は true です。

  • name

    文字列

    Cookie の名前。

  • partitionKey

    CookiePartitionKey（省略可）

    Chrome 119 以降

    Partitioned 属性を使用して Cookie を読み取ったり変更したりするためのパーティション キー。

  • パス

    文字列

    Cookie のパス。

  • sameSite

    SameSiteStatus

    Chrome 51 以降

    Cookie の同一サイト ステータス（Cookie がクロスサイト リクエストで送信されるかどうか）。

  • 安全

    ブール値

    クッキーが Secure としてマークされている場合（つまり、そのスコープが安全なチャネル（通常は HTTPS）に限定されている場合）は true。

  • セッション

    ブール値

    Cookie が有効期限のある永続 Cookie ではなく、セッション Cookie である場合は true。

  • storeId

    文字列

    getAllCookieStores() で指定されている、この Cookie を含む Cookie ストアの ID。

  • 値

    文字列

    Cookie の値。

CookieDetails

Chrome 88 以降

Cookie を識別するための詳細情報。

プロパティ

  • name

    文字列

    アクセスする Cookie の名前。

  • partitionKey

    CookiePartitionKey（省略可）

    Chrome 119 以降

    Partitioned 属性を使用して Cookie を読み取ったり変更したりするためのパーティション キー。

  • storeId

    文字列（省略可）

    Cookie を検索する Cookie ストアの ID。デフォルトでは、現在の実行コンテキストの Cookie ストアが使用されます。

  • URL

    文字列

    アクセスする Cookie が関連付けられている URL。この引数は完全な URL にすることもできます。その場合、URL パスの後のすべてのデータ（クエリ文字列など）は無視されます。この URL のホスト権限がマニフェスト ファイルで指定されていない場合、API 呼び出しは失敗します。

CookiePartitionKey

Chrome 119 以降

パーティション化された Cookie のパーティション キーを表します。

プロパティ

  • hasCrossSiteAncestor

    ブール値（省略可）

    Chrome 130 以降

    Cookie がクロスサイト コンテキストで設定されたかどうかを示します。これにより、クロスサイト コンテキストに埋め込まれたトップレベル サイトが、同じサイトのコンテキストでトップレベル サイトによって設定された Cookie にアクセスできなくなります。

  • topLevelSite

    文字列（省略可）

    パーティション化された Cookie を使用できるトップレベル サイト。

CookieStore

ブラウザの Cookie ストアを表します。たとえば、シークレット モード ウィンドウでは、シークレット モード以外のウィンドウとは別の Cookie ストアが使用されます。

プロパティ

  • id

    文字列

    Cookie ストアの一意の識別子。

  • tabIds

    number[]

    この Cookie ストアを共有するすべてのブラウザタブの識別子。

FrameDetails

保留中

フレームを特定するための詳細情報。

プロパティ

  • documentId

    文字列（省略可）

    ドキュメントの一意の識別子。frameId または tabId が指定されている場合は、指定されたドキュメント ID で見つかったドキュメントと一致するように検証されます。

  • frameId

    number（省略可）

    タブ内のフレームの一意の識別子。

  • tabId

    number（省略可）

    フレームを含むタブの一意の識別子。

OnChangedCause

Chrome 44 以降

クッキーの変更の根本的な理由。Cookie が挿入された場合、または「chrome.cookies.remove」の明示的な呼び出しによって削除された場合、「原因」は「明示的」になります。有効期限が切れたために Cookie が自動的に削除された場合、「原因」は「expired」になります。有効期限が切れた Cookie が上書きされたために削除された場合、「原因」は「expired_overwrite」に設定されます。ガベージ コレクションにより Cookie が自動的に削除された場合、「原因」は「evicted」になります。上書きされた「set」呼び出しにより Cookie が自動的に削除された場合、「原因」は「上書き」になります。それに応じて対応を計画します。

列挙型

「evicted」

「expired」

「explicit」

"expired_overwrite"

「overwrite」

SameSiteStatus

Chrome 51 以降

Cookie の「SameSite」状態（https://tools.ietf.org/html/draft-west-first-party-cookies）。「no_restriction」は「SameSite=None」で設定された Cookie に対応し、「lax」は「SameSite=Lax」、「strict」は「SameSite=Strict」に対応します。「unspecified」は、SameSite 属性なしで設定された Cookie に対応します。

列挙型

"no_restriction"

「lax」

"strict"

「未指定」

メソッド

get()

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

1 つの Cookie に関する情報を取得します。指定された URL に同じ名前の Cookie が複数存在する場合は、パスが最も長い Cookie が返されます。パスの長さが同じ Cookie の場合は、作成時間が最も早い Cookie が返されます。

パラメータ

  • 詳細

    CookieDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (cookie?: Cookie) => void

    • Cookie

      Cookie 省略可

      クッキーに関する詳細が含まれます。そのような Cookie が見つからない場合、このパラメータは null になります。

戻り値

  • Promise<Cookie | undefined>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getAll()

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

指定された情報に一致する Cookie を 1 つの Cookie ストアからすべて取得します。返された Cookie は、パスが長い順に並べ替えられます。複数の Cookie のパス長が同じ場合は、作成時間が最も早い Cookie が優先されます。このメソッドは、拡張機能にホスト権限があるドメインの Cookie のみを取得します。

パラメータ

  • 詳細

    オブジェクト

    取得する Cookie をフィルタするための情報。

    • ドメイン

      文字列（省略可）

      取得する Cookie を、このドメインと一致する Cookie またはこのドメインのサブドメインに限定します。

    • name

      文字列（省略可）

      クッキーを名前でフィルタします。

    • partitionKey

      CookiePartitionKey（省略可）

      Chrome 119 以降

      Partitioned 属性を使用して Cookie を読み取ったり変更したりするためのパーティション キー。

    • パス

      文字列（省略可）

      取得する Cookie を、パスがこの文字列と完全に一致するものに制限します。

    • 安全

      ブール値（省略可）

      Secure プロパティで Cookie をフィルタします。

    • セッション

      ブール値（省略可）

      セッション Cookie と永続 Cookie を除外します。

    • storeId

      文字列（省略可）

      Cookie を取得する Cookie ストア。省略した場合は、現在の実行コンテキストの Cookie ストアが使用されます。

    • URL

      文字列（省略可）

      取得する Cookie を、指定された URL に一致するものに制限します。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (cookies: Cookie[]) => void

    • Cookie

      Cookie[]

      指定された Cookie 情報に一致する、期限切れでない既存の Cookie すべて。

戻り値

  • Promise<Cookie[]>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getAllCookieStores()

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

既存のすべての Cookie ストアを一覧表示します。

パラメータ

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      既存の Cookie ストアすべて。

戻り値

  • Promise<CookieStore[]>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getPartitionKey()

Promise 保留中
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

指定されたフレームのパーティション キー。

パラメータ

  • 詳細

    FrameDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      取得されたパーティション キーの詳細が含まれます。

      • partitionKey

        CookiePartitionKey

        Partitioned 属性を使用して Cookie を読み取ったり変更したりするためのパーティション キー。

戻り値

  • Promise<object>

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

remove()

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

Cookie を名前で削除します。

パラメータ

  • 詳細

    CookieDetails

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (details?: object) => void

    • 詳細

      オブジェクト（省略可）

      削除された Cookie の詳細が含まれます。なんらかの理由で削除に失敗した場合は、この値は「null」になり、runtime.lastError が設定されます。

      • name

        文字列

        削除された Cookie の名前。

      • partitionKey

        CookiePartitionKey（省略可）

        Chrome 119 以降

        Partitioned 属性を使用して Cookie を読み取ったり変更したりするためのパーティション キー。

      • storeId

        文字列

        Cookie が削除された Cookie ストアの ID。

      • URL

        文字列

        削除された Cookie に関連付けられている URL。

戻り値

  • Promise<object | undefined>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

set()

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

指定された Cookie データを使用して Cookie を設定します。同等の Cookie が存在する場合は上書きされることがあります。

パラメータ

  • 詳細

    オブジェクト

    設定される Cookie の詳細。

    • ドメイン

      文字列（省略可）

      Cookie のドメイン。省略すると、Cookie はホスト専用 Cookie になります。

    • expirationDate

      number（省略可）

      Cookie の有効期限（UNIX エポックからの秒数）。省略すると、Cookie はセッション Cookie になります。

    • httpOnly

      ブール値（省略可）

      Cookie を HttpOnly としてマークするかどうか。デフォルトは false です。

    • name

      文字列（省略可）

      Cookie の名前。省略した場合はデフォルトで空になります。

    • partitionKey

      CookiePartitionKey（省略可）

      Chrome 119 以降

      Partitioned 属性を使用して Cookie を読み取ったり変更したりするためのパーティション キー。

    • パス

      文字列（省略可）

      Cookie のパス。デフォルトは、url パラメータのパス部分です。

    • sameSite

      SameSiteStatus（省略可）

      Chrome 51 以降

      Cookie の同一サイトのステータス。デフォルトは「unspecified」です。省略した場合、SameSite 属性を指定せずに Cookie が設定されます。

    • 安全

      ブール値（省略可）

      Cookie を Secure としてマークするかどうか。デフォルトは false です。

    • storeId

      文字列（省略可）

      Cookie を設定する Cookie ストアの ID。デフォルトでは、Cookie は現在の実行コンテキストの Cookie ストアに設定されます。

    • URL

      文字列

      Cookie の設定に関連付けるリクエスト URI。この値は、作成される Cookie のデフォルトのドメイン値とパス値に影響する可能性があります。この URL のホスト権限がマニフェスト ファイルで指定されていない場合、API 呼び出しは失敗します。

    • 値

      文字列（省略可）

      Cookie の値。省略した場合はデフォルトで空になります。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    (cookie?: Cookie) => void

    • Cookie

      Cookie 省略可

      設定された Cookie の詳細が含まれます。なんらかの理由で設定に失敗した場合、この値は「null」になり、runtime.lastError が設定されます。

戻り値

  • Promise<Cookie | undefined>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

イベント

onChanged

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

Cookie が設定または削除されたときに発動します。特殊なケースとして、Cookie のプロパティの更新は 2 段階のプロセスとして実装されます。まず、更新対象の Cookie が完全に削除され、通知が生成されます。この通知の「原因」は「上書き」です。その後、更新された値を含む新しい Cookie が書き込まれ、2 つ目の通知が「原因」が「明示的」で生成されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (changeInfo: object) => void

    • changeInfo

      オブジェクト

      • クッキーの変更の根本的な理由。

      • Cookie

        Cookie

        設定または削除された Cookie に関する情報。

      • 削除済み

        ブール値

        Cookie が削除された場合は true。