chrome.cookies

Deskripsi

Gunakan chrome.cookies API untuk membuat kueri 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 setiap 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 berdasarkan asal frame tingkat atas. 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 cookies 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

    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+

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

    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 atas tempat cookie yang dipartisi tersedia.

CookieStore

Mewakili penyimpanan cookie di browser. Misalnya, jendela mode samaran menggunakan penyimpanan cookie 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

Tertunda

Detail untuk mengidentifikasi bingkai.

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+

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 dihapus secara otomatis karena pembersihan sampah, "cause" akan "dihapus". Jika cookie dihapus secara otomatis karena panggilan "set" yang menimpanya, "cause" akan menjadi "overwrite". Rencanakan respons Anda dengan tepat.

Enum

"evicted"

"expired"

"explicit"

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

Enum

"no_restriction"

"longgar"

"strict"

"unspecified"

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 bernilai null jika tidak ada cookie tersebut yang ditemukan.

Hasil

  • Promise<Cookie | undefined>

    Chrome 88+

    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 dengan waktu pembuatan paling awal akan diprioritaskan. Metode ini hanya mengambil cookie untuk domain yang memiliki izin host untuk 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 domain ini.

    • nama

      string opsional

      Memfilter cookie menurut nama.

    • partitionKey

      CookiePartitionKey opsional

      Chrome 119+

      Kunci partisi untuk membaca atau mengubah cookie dengan atribut 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 belum habis masa berlakunya yang cocok dengan info cookie yang diberikan.

Hasil

  • Promise<Cookie[]>

    Chrome 88+

    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+

    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.

getPartitionKey()

Promise Tertunda
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

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 Dipartisi.

Hasil

  • Promise&lt;object&gt;

    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 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, nilai ini 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 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 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 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+

      Kunci partisi untuk membaca atau mengubah cookie dengan atribut Dipartisi.

    • jalur

      string opsional

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

    • sameSite

      SameSiteStatus opsional

      Chrome 51+

      Status situs yang sama untuk 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 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: 

    (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+

    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.

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: 

    (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.