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 Cookies API, Anda harus mendeklarasikan izin "cookies" di manifes, beserta izin host untuk host 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 diberi kunci terhadap origin frame tingkat teratas. 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 partisi, yang berarti semua metode membaca dan menulis cookie dari semua partisi. Metode cookies.set() menyimpan cookie di partisi default.

Untuk mengetahui detail 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 Contoh.

Jenis

Menampilkan informasi tentang cookie HTTP.

Properti

  • domain

    string

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

  • expirationDate

    nomor opsional

    Tanggal habis masa berlaku cookie sebagai 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 (True) 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 yang Dipartisi.

  • jalur

    string

    Jalur cookie.

  • sameSite

    SameSiteStatus

    Chrome 51+

    Status same-site 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 (True) jika cookie adalah cookie sesi, bukan cookie persisten dengan tanggal habis masa berlaku.

  • storeId

    string

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

  • nilai

    string

    Nilai cookie.

CookieDetails

Chrome 88+

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 cookie akan dicari. 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 (misalnya, 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 yang dipartisi.

Properti

  • hasCrossSiteAncestor

    boolean opsional

    Chrome 130+

    Menunjukkan apakah cookie disetel dalam konteks lintas situs. Tindakan 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 atas 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 berbagi penyimpanan cookie ini.

FrameDetails

Chrome 132+

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

    nomor opsional

    ID unik untuk frame dalam tab.

  • tabId

    nomor opsional

    ID unik untuk tab yang berisi frame.

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 otomatis dihapus karena masa berlakunya berakhir, "penyebab" akan menjadi "masa berlaku berakhir". Jika cookie dihapus karena ditimpa dengan tanggal habis masa berlaku yang sudah berakhir, "penyebab" akan disetel ke "expired_overwrite". Jika cookie dihapus secara otomatis karena pengumpulan sampah, "penyebab" akan menjadi "dikeluarkan". Jika cookie dihapus secara otomatis karena panggilan "set" yang menimpanya, "cause" akan menjadi "overwrite". Rencanakan respons Anda dengan tepat.

Enum

"dikeluarkan"

"expired"

"eksplisit"

"expired_overwrite"

"overwrite"

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' sesuai dengan 'SameSite=Lax', dan 'strict' sesuai dengan 'SameSite=Strict'. 'unspecified' sesuai dengan cookie yang ditetapkan tanpa atribut SameSite.

Enum

"no_restriction"

"lax"

"strict"

"tidak ditentukan"

Metode

get()

Janji 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

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 adalah null jika tidak ada cookie seperti itu yang ditemukan.

Hasil

  • Promise<Cookie | undefined>

    Chrome 88+

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

getAll()

Janji 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): 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 ditampilkan terlebih dahulu. Metode ini hanya mengambil cookie untuk domain yang memiliki izin host 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+

      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 Secure-nya.

    • sesi

      boolean opsional

      Memfilter cookie sesi vs. persisten.

    • storeId

      string opsional

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

    • url

      string opsional

      Membatasi cookie yang diambil ke cookie yang 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+

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

getAllCookieStores()

Janji 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

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+

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

getPartitionKey()

Promise Chrome 132+ 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

Kunci partisi untuk frame yang ditunjukkan.

Parameter

  • detail

    FrameDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (details: object) => void

    • detail

      objek

      Berisi detail tentang kunci partisi yang telah diambil.

      • partitionKey

        CookiePartitionKey

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

Hasil

  • Promise<object>

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

remove()

Janji 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

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, promise akan ditolak.

      • 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 Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.

set()

Janji 
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

Menetapkan cookie dengan data cookie yang diberikan; dapat menggantikan 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

      nomor opsional

      Tanggal habis masa berlaku cookie sebagai jumlah detik sejak epoch UNIX. Jika tidak disertakan, 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 tidak disertakan.

    • partitionKey

      CookiePartitionKey opsional

      Chrome 119+

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

    • jalur

      string opsional

      Jalur cookie. Secara default, nilainya adalah bagian jalur parameter URL.

    • sameSite

      SameSiteStatus opsional

      Chrome 51+

      Status same-site cookie. Defaultnya 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 akan disetel. Secara default, cookie disetel di penyimpanan cookie konteks eksekusi saat ini.

    • url

      string

      request-URI untuk 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 tidak disertakan.

  • 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, promise akan ditolak.

Hasil

  • Promise<Cookie | undefined>

    Chrome 88+

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

Acara

onChanged

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

Diaktifkan saat cookie disetel atau dihapus. Sebagai kasus khusus, perhatikan bahwa memperbarui properti cookie diimplementasikan sebagai proses dua langkah: cookie yang akan diperbarui dihapus terlebih dahulu sepenuhnya, sehingga menghasilkan notifikasi dengan "penyebab" "ditimpa" . 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 mendasar di balik perubahan cookie.

      • kue

        Cookie

        Informasi tentang cookie yang ditetapkan atau dihapus.

      • dihapus

        boolean

        Benar jika cookie dihapus.