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
Cookie
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.
-
sameSiteChrome 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
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
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
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
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()
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
Hasil
-
Promise<Cookie | undefined>
Chrome 88 dan yang lebih baruPromise 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()
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 baruPromise 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()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Mencantumkan semua penyimpanan cookie yang ada.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(cookieStores: CookieStore[]) => void
-
cookieStores
Semua penyimpanan cookie yang ada.
-
Hasil
-
Promise<CookieStore[]>
Chrome 88 dan yang lebih baruPromise 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()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Menghapus cookie berdasarkan nama.
Parameter
-
detail
-
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 baruPromise 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()
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 baruPromise 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.
Acara
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
-
cause
Alasan yang mendasari perubahan cookie.
-
kue
Informasi tentang cookie yang ditetapkan atau dihapus.
-
dihapus
boolean
True jika cookie dihapus.
-
-