browser.cookies

Deskripsi

Gunakan chrome.cookies API untuk mengkueri dan mengubah cookie, serta untuk mendapatkan notifikasi saat cookie berubah.

Izin

cookies

Untuk menggunakan cookies API, deklarasikan izin "cookies" dalam manifes Anda beserta izin host untuk host mana pun yang cookie-nya ingin Anda akses. Contoh:

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

Membuat partisi

Cookie yang dipartisi memungkinkan situs menandai bahwa cookie tertentu harus dikunci terhadap asal frame tingkat teratas. Artinya, misalnya, jika situs A disematkan menggunakan iframe di situs B dan situs C, versi sematan cookie yang dipartisi dari A dapat memiliki nilai yang berbeda di B dan C.

Secara default, semua metode API beroperasi pada cookie yang tidak dipartisi. Properti partitionKey dapat digunakan untuk mengganti perilaku ini.

Untuk mengetahui detail tentang dampak umum partisi untuk ekstensi, lihat Penyimpanan dan Cookie.

Contoh

Anda dapat menemukan contoh sederhana penggunaan API cookie di direktori examples/api/cookies. Untuk contoh lain dan bantuan dalam melihat kode sumber, lihat Contoh.

Jenis

Cookie

Menampilkan informasi tentang cookie HTTP.

Properti

• domain

  string

  Domain cookie (misalnya, "www.google.com", "example.com").

• expirationDate

  number opsional

  Tanggal habis masa berlaku cookie sebagai jumlah detik sejak epoch UNIX. Tidak disediakan untuk cookie sesi.

• hostOnly

  boolean

  True jika cookie adalah cookie khusus host (yaitu, host permintaan harus sama persis dengan domain cookie).

• httpOnly

  boolean

  True jika cookie ditandai sebagai HttpOnly (yaitu, cookie tidak dapat diakses oleh skrip sisi klien).

• nama

  string

  Nama cookie.

• partitionKey

  CookiePartitionKey opsional

  Chrome 119+ browser.* sejak Chrome 148

  Kunci partisi untuk membaca atau mengubah cookie dengan atribut Partitioned.

• jalur

  string

  Jalur cookie.

• sameSite

  SameSiteStatus

  Chrome 51+ browser.* sejak Chrome 148

  Status same-site cookie (yaitu, apakah cookie dikirim dengan permintaan lintas situs).

• aman

  boolean

  True jika cookie ditandai sebagai Aman (yaitu, cakupannya terbatas pada saluran aman, biasanya HTTPS).

• sesi

  boolean

  True jika cookie adalah cookie sesi, bukan cookie persisten dengan tanggal habis masa berlaku.

• storeId

  string

  ID penyimpanan cookie yang berisi cookie ini, seperti yang disediakan di getAllCookieStores().

• nilai

  string

  Nilai cookie.

CookieDetails

Chrome 88+ browser.* sejak Chrome 148

Detail untuk mengidentifikasi cookie.

Properti

• nama

  string

  Nama cookie yang akan diakses.

• partitionKey

  CookiePartitionKey opsional

  Chrome 119+ browser.* sejak Chrome 148

  Kunci partisi untuk membaca atau mengubah cookie dengan atribut Partitioned.

• storeId

  string opsional

  ID penyimpanan cookie tempat mencari cookie. Secara default, penyimpanan cookie konteks eksekusi saat ini akan digunakan.

• url

  string

  URL yang terkait dengan cookie yang akan diakses. Argumen ini dapat berupa URL lengkap, yang dalam hal ini data apa pun yang mengikuti jalur URL (misalnya string kueri) akan diabaikan. Jika izin host untuk URL ini tidak ditentukan dalam file manifes, panggilan API akan gagal.

CookiePartitionKey

Chrome 119+ browser.* sejak Chrome 148

Merepresentasikan kunci partisi dari cookie yang dipartisi.

Properti

• hasCrossSiteAncestor

  boolean opsional

  Chrome 130+ browser.* sejak Chrome 148

  Menunjukkan apakah cookie ditetapkan dalam konteks lintas situs. Hal ini mencegah situs tingkat teratas yang disematkan dalam konteks lintas situs mengakses cookie yang ditetapkan oleh situs tingkat teratas dalam konteks situs yang sama.

• topLevelSite

  string opsional

  Situs tingkat teratas tempat cookie yang dipartisi tersedia.

CookieStore

Mewakili penyimpanan cookie di browser. Misalnya, jendela mode samaran menggunakan penyimpanan cookie yang terpisah dari jendela non-samaran.

Properti

• id

  string

  ID unik untuk penyimpanan cookie.

• tabIds

  number[]

  ID semua tab browser yang menggunakan penyimpanan cookie ini.

FrameDetails

Chrome 132+ browser.* sejak Chrome 148

Detail untuk mengidentifikasi frame.

Properti

• documentId

  string opsional

  ID unik untuk dokumen. Jika frameId dan/atau tabId diberikan, keduanya akan divalidasi agar cocok dengan dokumen yang ditemukan oleh ID dokumen yang diberikan.

• frameId

  number opsional

  ID unik untuk frame dalam tab.

• tabId

  number opsional

  ID unik untuk tab yang berisi frame.

OnChangedCause

Chrome 44+ browser.* sejak Chrome 148

Alasan mendasar di balik perubahan cookie. Jika cookie disisipkan, atau dihapus melalui panggilan eksplisit ke "chrome.cookies.remove", "cause" akan menjadi "explicit". Jika cookie otomatis dihapus karena masa berlakunya habis, "cause" akan menjadi "expired". Jika cookie dihapus karena ditimpa dengan tanggal habis masa berlaku yang sudah tidak berlaku, "cause" akan ditetapkan ke "expired_overwrite". Jika cookie otomatis dihapus karena pembersihan sampah memori, "cause" akan menjadi "evicted". Jika cookie otomatis dihapus karena panggilan "set" yang menimpanya, "cause" akan menjadi "overwrite". Rencanakan respons Anda dengan tepat.

Enum

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51+ browser.* sejak Chrome 148

Status 'SameSite' cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' sesuai dengan cookie yang ditetapkan dengan 'SameSite=None', 'lax' dengan 'SameSite=Lax', dan 'strict' dengan 'SameSite=Strict'. 'unspecified' sesuai dengan cookie yang ditetapkan tanpa atribut SameSite.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Metode

get()

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

Mengambil informasi tentang satu cookie. Jika ada lebih dari satu cookie dengan nama yang sama untuk URL yang diberikan, cookie dengan jalur terpanjang akan ditampilkan. Untuk cookie dengan panjang jalur yang sama, cookie dengan waktu pembuatan paling awal akan ditampilkan.

Parameter

• detail

  CookieDetails

Hasil

• Promise<Cookie | undefined>

  Chrome 88+ browser.* sejak Chrome 148

getAll()

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

Mengambil semua cookie dari satu penyimpanan cookie yang cocok dengan informasi yang diberikan. Cookie yang ditampilkan akan diurutkan, dengan cookie yang memiliki jalur terpanjang terlebih dahulu. Jika beberapa cookie memiliki panjang jalur yang sama, cookie dengan waktu pembuatan paling awal akan diutamakan. Metode ini hanya mengambil cookie untuk domain yang izin host-nya dimiliki oleh ekstensi.

Parameter

• detail

  objek

  Informasi untuk memfilter cookie yang diambil.

  • domain

    string opsional

    Membatasi cookie yang diambil hanya untuk cookie yang domainnya cocok atau merupakan subdomain dari domain ini.

  • nama

    string opsional

    Memfilter cookie menurut nama.

  • partitionKey

    CookiePartitionKey opsional

    Chrome 119+ browser.* sejak Chrome 148

    Kunci partisi untuk membaca atau mengubah cookie dengan atribut Partitioned.

  • jalur

    string opsional

    Membatasi cookie yang diambil hanya pada cookie yang jalurnya sama persis dengan string ini.

  • aman

    boolean opsional

    Memfilter cookie berdasarkan properti Secure-nya.

  • sesi

    boolean opsional

    Memfilter cookie sesi vs. cookie persisten.

  • storeId

    string opsional

    Penyimpanan cookie tempat cookie diambil. Jika dihilangkan, penyimpanan cookie konteks eksekusi saat ini akan digunakan.

  • url

    string opsional

    Membatasi cookie yang diambil hanya pada cookie yang cocok dengan URL yang diberikan.

Hasil

• Promise<Cookie[]>

  Chrome 88+ browser.* sejak Chrome 148

getAllCookieStores()

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

Mencantumkan semua penyimpanan cookie yang ada.

Hasil

• Promise<CookieStore[]>

  Chrome 88+ browser.* sejak Chrome 148

getPartitionKey()

Chrome 132+ browser.* sejak Chrome 148

browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Kunci partisi untuk frame yang ditunjukkan.

Parameter

• detail

  FrameDetails

Hasil

• Promise<object>

remove()

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

Menghapus cookie berdasarkan nama.

Parameter

• detail

  CookieDetails

Hasil

• Promise<object | undefined>

  Chrome 88+ browser.* sejak Chrome 148

set()

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

Menetapkan cookie dengan data cookie yang diberikan; dapat menimpa cookie yang setara jika ada.

Parameter

• detail

  objek

  Detail tentang cookie yang ditetapkan.

  • domain

    string opsional

    Domain cookie. Jika dihilangkan, cookie akan menjadi cookie khusus host.

  • expirationDate

    number opsional

    Tanggal habis masa berlaku cookie sebagai jumlah detik sejak epoch UNIX. Jika dihilangkan, cookie akan menjadi cookie sesi.

  • httpOnly

    boolean opsional

    Apakah cookie harus ditandai sebagai HttpOnly. Nilai defaultnya adalah false (salah).

  • nama

    string opsional

    Nama cookie. Kosong secara default jika dihilangkan.

  • partitionKey

    CookiePartitionKey opsional

    Chrome 119+ browser.* sejak Chrome 148

    Kunci partisi untuk membaca atau mengubah cookie dengan atribut Partitioned.

  • jalur

    string opsional

    Jalur cookie. Default-nya adalah bagian jalur parameter URL.

  • sameSite

    SameSiteStatus opsional

    Chrome 51+ browser.* sejak Chrome 148

    Status same-site cookie. Setelan default ditetapkan ke "unspecified", yaitu, jika dihilangkan, cookie akan ditetapkan tanpa menentukan atribut SameSite.

  • aman

    boolean opsional

    Apakah cookie harus ditandai sebagai Aman. Nilai defaultnya adalah false (salah).

  • storeId

    string opsional

    ID penyimpanan cookie tempat cookie akan ditetapkan. Secara default, cookie ditetapkan di penyimpanan cookie konteks eksekusi saat ini.

  • url

    string

    URI permintaan yang akan dikaitkan dengan setelan cookie. Nilai ini dapat memengaruhi nilai domain dan jalur default cookie yang dibuat. Jika izin host untuk URL ini tidak ditentukan dalam file manifes, panggilan API akan gagal.

  • nilai

    string opsional

    Nilai cookie. Kosong secara default jika dihilangkan.

Hasil

• Promise<Cookie | undefined>

  Chrome 88+ browser.* sejak Chrome 148

Acara

onChanged

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

Diaktifkan saat cookie ditetapkan atau dihapus. Sebagai kasus khusus, perhatikan bahwa memperbarui properti cookie diimplementasikan sebagai proses dua langkah: cookie yang akan diperbarui pertama-tama dihapus sepenuhnya, menghasilkan notifikasi dengan "cause" dari "overwrite" . Setelah itu, cookie baru akan ditulis dengan nilai yang diperbarui, sehingga menghasilkan notifikasi kedua dengan "cause" "explicit".

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (changeInfo: object) => void

  • changeInfo

    objek

    • cause

      OnChangedCause

      Alasan mendasar di balik perubahan cookie.

    • kue

      Cookie

      Informasi tentang cookie yang ditetapkan atau dihapus.

    • dihapus

      boolean

      True jika cookie dihapus.