chrome.cookies

Deskripsi

Gunakan chrome.cookies API untuk membuat kueri dan mengubah cookie, serta agar diberi tahu saat cookie berubah.

Izin

cookies

Untuk menggunakan API cookie, deklarasikan izin "cookies" dalam manifes Anda bersama dengan izin host untuk setiap host yang cookie-nya ingin Anda akses. Contoh:

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

Membuat partisi

Cookie partisi memungkinkan situs menandai bahwa cookie tertentu harus dikunci berdasarkan asal frame tingkat atas. Artinya, jika situs A disematkan menggunakan iframe di situs B dan situs C, versi tersemat cookie terpartisi 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 cookie API di direktori examples/api/cookies. Untuk contoh lain dan bantuan dalam melihat kode sumber, lihat Sample.

Jenis

Menampilkan informasi tentang cookie HTTP.

Properti

  • domain

    string

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

  • expirationDate

    nomor opsional

    Tanggal habis masa berlaku cookie adalah 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).

  • name

    string

    Nama cookie.

  • partitionKey

    CookiePartitionKey opsional

    Chrome 119+

    Kunci partisi untuk membaca atau mengubah cookie dengan atribut Terpartisi.

  • jalur

    string

    Jalur cookie.

  • sameSite

    SameSiteStatus

    Chrome 51+

    Status situs yang sama cookie (yaitu apakah cookie dikirim dengan permintaan lintas situs atau tidak).

  • aman

    boolean

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

  • session

    boolean

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

  • storeId

    string

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

  • value

    string

    Nilai cookie.

CookieDetails

Chrome 88 dan yang lebih baru

Detail untuk mengidentifikasi cookie.

Properti

  • name

    string

    Nama cookie yang akan diakses.

  • partitionKey

    CookiePartitionKey opsional

    Chrome 119+

    Kunci partisi untuk membaca atau mengubah cookie dengan atribut Terpartisi.

  • storeId

    string opsional

    ID toko 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, sehingga data apa pun yang mengikuti jalur URL (mis. string kueri) akan diabaikan. Jika izin host untuk URL ini tidak ditentukan dalam file manifes, panggilan API akan gagal.

CookiePartitionKey

Chrome 119+

Mewakili kunci partisi cookie terpartisi.

Properti

  • topLevelSite

    string opsional

    Situs tingkat teratas tempat cookie terpartisi tersedia.

CookieStore

Mewakili penyimpanan cookie di browser. Jendela mode samaran, misalnya, menggunakan penyimpanan cookie yang terpisah dari jendela selain samaran.

Properti

  • id

    string

    ID unik untuk toko cookie.

  • tabIds

    angka[]

    ID dari semua tab browser yang berbagi penyimpanan cookie ini.

OnChangedCause

Chrome 44+

Alasan yang mendasari perubahan cookie. Jika cookie disisipkan, atau dihapus melalui panggilan eksplisit ke "chrome.cookies.remove", "karena" akan menjadi "eksplisit". Jika cookie dihapus secara otomatis karena masa berlakunya telah berakhir, "penyebab" akan "habis masa berlakunya". Jika cookie dihapus karena ditimpa dengan tanggal habis masa berlaku yang sudah berakhir, "karena" akan ditetapkan ke "expiration_overwrite". Jika cookie dihapus secara otomatis karena pembersihan sampah memori, "penyebab" akan "dikeluarkan". Jika cookie dihapus secara otomatis karena panggilan "set" yang menimpanya, "karena" akan menjadi "timpa". Rencanakan respons Anda dengan tepat.

Enum

SameSiteStatus

Chrome 51+

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

Enum

"no_restriction"

"lax"

Metode

get()

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

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

Parameter

  • detail

    CookieDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (cookie?: Cookie)=>void

    • kue

      Cookie opsional

      Berisi detail tentang cookie. Parameter ini null jika cookie tersebut tidak ditemukan.

Hasil

  • Promise<Cookie|undefined>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getAll()

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

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 yang memiliki waktu pembuatan paling awal akan menjadi yang pertama. Metode ini hanya mengambil cookie untuk domain yang izin host-nya dimiliki ekstensi.

Parameter

  • detail

    objek

    Informasi untuk memfilter cookie yang diambil.

    • domain

      string opsional

      Membatasi cookie yang diambil ke cookie yang domainnya cocok atau merupakan subdomain dari cookie ini.

    • name

      string opsional

      Memfilter cookie menurut nama.

    • partitionKey

      CookiePartitionKey opsional

      Chrome 119+

      Kunci partisi untuk membaca atau mengubah cookie dengan atribut Terpartisi.

    • jalur

      string opsional

      Membatasi cookie yang diambil ke cookie yang jalurnya sama persis dengan string ini.

    • aman

      boolean opsional

      Memfilter cookie menurut properti Secure-nya.

    • session

      boolean opsional

      Memfilter cookie sesi vs. cookie persisten.

    • storeId

      string opsional

      Penyimpanan cookie untuk mengambil cookie. Jika dihilangkan, penyimpanan cookie konteks eksekusi saat ini akan digunakan.

    • url

      string opsional

      Membatasi cookie yang diambil ke cookie yang akan cocok dengan URL yang diberikan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (cookies: Cookie[])=>void

    • cookie

      Cookie[]

      Semua cookie yang ada dan belum habis masa berlakunya yang cocok dengan info cookie yang diberikan.

Hasil

  • Promise<Cookie[]>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getAllCookieStores()

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

Mencantumkan semua penyimpanan cookie yang ada.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      Semua penyimpanan cookie yang ada.

Hasil

  • Promise<CookieStore[]>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

remove()

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

Menghapus cookie berdasarkan nama.

Parameter

  • detail

    CookieDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (details?: object)=>void

    • detail

      objek opsional

      Berisi detail tentang cookie yang telah dihapus. Jika penghapusan gagal karena alasan apa pun, nilainya akan menjadi "null", dan runtime.lastError akan ditetapkan.

      • name

        string

        Nama cookie yang telah dihapus.

      • partitionKey

        CookiePartitionKey opsional

        Chrome 119+

        Kunci partisi untuk membaca atau mengubah cookie dengan atribut Terpartisi.

      • storeId

        string

        ID toko cookie tempat cookie dihapus.

      • url

        string

        URL yang terkait dengan cookie yang telah dihapus.

Hasil

  • Promise<object|undefined>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

set()

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

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 dihapus, cookie akan menjadi cookie khusus host.

    • expirationDate

      nomor opsional

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

    • httpOnly

      boolean opsional

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

    • name

      string opsional

      Nama cookie. Kosong secara default jika dihilangkan.

    • partitionKey

      CookiePartitionKey opsional

      Chrome 119+

      Kunci partisi untuk membaca atau mengubah cookie dengan atribut Terpartisi.

    • jalur

      string opsional

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

    • sameSite

      SameSiteStatus opsional

      Chrome 51+

      Status situs yang sama cookie. Default-nya adalah "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 toko cookie tempat untuk menetapkan cookie. Secara default, cookie disetel di penyimpanan cookie konteks eksekusi saat ini.

    • url

      string

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

    • value

      string opsional

      Nilai cookie. Kosong secara default jika dihilangkan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (cookie?: Cookie)=>void

    • kue

      Cookie opsional

      Berisi detail tentang cookie yang telah ditetapkan. Jika setelan gagal karena alasan apa pun, nilainya akan menjadi "null", dan runtime.lastError akan ditetapkan.

Hasil

  • Promise<Cookie|undefined>

    Chrome 88 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

Peristiwa

onChanged

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

Diaktifkan saat cookie ditetapkan atau dihapus. Sebagai kasus khusus, perhatikan bahwa pembaruan properti cookie diterapkan melalui proses dua langkah: cookie yang akan diperbarui pertama-tama dihapus secara keseluruhan, sehingga menghasilkan pemberitahuan dengan "penyebab" "menimpa" . Setelah itu, cookie baru ditulis dengan nilai yang diperbarui, sehingga menghasilkan notifikasi kedua dengan "penyebab" "eksplisit".

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (changeInfo: object)=>void

    • changeInfo

      objek

      • Alasan yang mendasari perubahan cookie.

      • kue

        Cookie

        Informasi tentang cookie yang ditetapkan atau dihapus.

      • dihapus

        boolean

        True jika cookie dihapus.