chrome.cookies

Deskripsi

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

Izin

cookies

Manifes

Untuk menggunakan API cookie, Anda harus mendeklarasikan "cookie" izin di manifes, beserta izin host untuk setiap host yang cookie-nya Anda inginkan untuk diakses. Contoh:

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

Membuat partisi

Cookie berpartisi memungkinkan situs menandai bahwa cookie tertentu harus disertakan pada asal dari {i>frame <i}tingkat atas. Artinya, jika situs A disematkan menggunakan iframe di situs B dan situs C, cookie yang dipartisi dapat memiliki nilai yang berbeda di setiap situs.

chrome.cookies tidak mendukung pembuatan partisi, yang berarti bahwa semua metode membaca dan menulis {i> cookie<i} dari semua partisi. Metode cookies.set() menyimpan cookie di partisi {i>default<i}.

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

Contoh

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

Jenis

Menampilkan informasi tentang cookie HTTP.

Properti

  • domain

    string

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

  • expirationDate

    number opsional

    Tanggal berakhir cookie berupa jumlah detik sejak epoch UNIX. Tidak disediakan untuk cookie sesi.

  • hostOnly

    boolean

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

  • httpOnly

    boolean

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

  • nama

    string

    Nama cookie.

  • partitionKey

    CookiePartitionKey opsional

    Chrome 119+

    Kunci partisi untuk membaca atau mengubah cookie dengan atribut Dipartisi.

  • jalur

    string

    Jalur cookie.

  • sameSite

    SameSiteStatus

    Chrome 51+

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

  • aman

    boolean

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

  • sesi

    boolean

    Benar 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 dan yang lebih baru

Detail untuk mengidentifikasi cookie.

Properti

  • nama

    string

    Nama cookie yang akan diakses.

  • partitionKey

    CookiePartitionKey opsional

    Chrome 119+

    Kunci partisi untuk membaca atau mengubah cookie dengan atribut yang dipartisi.

  • 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, 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+

Merepresentasikan kunci partisi cookie yang dipartisi.

Properti

  • hasCrossSiteAncestor

    boolean opsional

    Chrome 130 dan yang lebih baru

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

  • topLevelSite

    string opsional

    Situs tingkat teratas tempat cookie yang dipartisi tersedia.

CookieStore

Menampilkan penyimpanan cookie di browser. Jendela mode samaran, misalnya, menggunakan penyimpanan cookie terpisah dari jendela non-Samaran.

Properti

  • id

    string

    ID unik untuk penyimpanan cookie.

  • tabIds

    number[]

    ID semua tab browser yang membagikan penyimpanan cookie ini.

OnChangedCause

Chrome 44+

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

Enum

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 dan yang lebih baru

'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'. 'belum ditetapkan' sesuai dengan cookie yang ditetapkan tanpa atribut SameSite.

Enum

"longgar"

Metode

get()

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

Mengambil informasi tentang cookie tunggal. Jika terdapat 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

  • 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 | tidak terdefinisi>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan 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 dengan waktu pembuatan paling awal akan diprioritaskan. Metode ini hanya mengambil cookie untuk domain yang izin hostnya dimiliki ekstensi.

Parameter

  • detail

    objek

    Informasi untuk memfilter cookie yang diambil.

    • domain

      string opsional

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

    • nama

      string opsional

      Memfilter cookie menurut nama.

    • partitionKey

      CookiePartitionKey opsional

      Chrome 119 dan yang lebih baru

      Kunci partisi untuk membaca atau mengubah cookie dengan atribut yang dipartisi.

    • jalur

      string opsional

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

    • aman

      boolean opsional

      Memfilter cookie berdasarkan properti Aman.

    • sesi

      boolean opsional

      Memfilter cookie sesi vs. cookie persisten.

    • storeId

      string opsional

      Penyimpanan cookie tempat 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 masih berlaku yang cocok dengan info cookie yang diberikan.

Hasil

  • Janji<Cookie[]>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan 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 hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

remove()

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

Menghapus cookie menurut 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.

      • nama

        string

        Nama cookie yang telah dihapus.

      • partitionKey

        CookiePartitionKey opsional

        Chrome 119+

        Kunci partisi untuk membaca atau mengubah cookie dengan atribut yang dipartisi.

      • storeId

        string

        ID penyimpanan cookie tempat cookie dihapus.

      • url

        string

        URL yang terkait dengan cookie yang telah dihapus.

Hasil

  • Promise<object | undefined>

    Chrome 88+

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

set()

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

    • expirationDate

      number opsional

      Tanggal berakhir cookie berupa 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 dan yang lebih baru

      Kunci partisi untuk membaca atau mengubah cookie dengan atribut Dipartisi.

    • jalur

      string opsional

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

    • sameSite

      SameSiteStatus opsional

      Chrome 51+

      Status situs yang sama untuk 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 penyimpanan cookie tempat cookie 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.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (cookie?: Cookie) => void

    • kue

      Cookie opsional

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

Hasil

  • Promise<Cookie | undefined>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

Acara

onChanged

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

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

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (changeInfo: object) => void

    • changeInfo

      objek

      • Alasan mendasar di balik perubahan cookie.

      • kue

        Cookie

        Informasi tentang cookie yang ditetapkan atau dihapus.

      • dihapus

        boolean

        Benar jika cookie dihapus.