chrome.cookies

Açıklama

Çerezleri sorgulamak ve değiştirmek ve değiştiklerinde bildirim almak için chrome.cookies API'yi kullanın.

İzinler

cookies

Çerez API'sini kullanmak için manifest dosyanızda, çerezlerine erişmek istediğiniz tüm ana makineler için "cookies" iznini ve ana makine izinlerini beyan edin. Örneğin:

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

Bölümlendirme

Bölümlendirilmiş çerezler, bir sitenin belirli çerezlerin üst düzey çerçevenin kaynağına göre anahtarlanması gerektiğini işaretlemesine olanak tanır. Bu, örneğin, A sitesi B ve C sitelerinde bir iframe kullanılarak yerleştirilmişse A sitesindeki bölümlenmiş bir çerezin yerleştirilmiş sürümlerinin B ve C'de farklı değerlere sahip olabileceği anlamına gelir.

Varsayılan olarak tüm API yöntemleri, bölümlenmemiş çerezlerle çalışır. Bu davranışı geçersiz kılmak için partitionKey özelliği kullanılabilir.

Bölümlendirmenin uzantılar üzerindeki genel etkisi hakkında ayrıntılı bilgi için Depolama alanı ve çerezler başlıklı makaleyi inceleyin.

Örnekler

examples/api/cookies dizininde, cookies API'nin kullanıldığı basit bir örnek bulabilirsiniz. Diğer örnekler ve kaynak kodu görüntülemeyle ilgili yardım için Örnekler bölümüne bakın.

Türler

HTTP çereziyle ilgili bilgileri temsil eder.

Özellikler

  • alan

    dize

    Çerezin alanı (ör. "www.google.com", "example.com").

  • expirationDate

    number isteğe bağlı

    UNIX sıfır zamanından itibaren geçen saniye sayısı olarak çerezin geçerlilik bitiş tarihi. Oturum çerezleri için sağlanmaz.

  • hostOnly

    boolean

    Çerez yalnızca ana makine çereziyse (yani istek ana makinesinin çerezin alan adıyla tam olarak eşleşmesi gerekir) doğru değerini alır.

  • httpOnly

    boolean

    Çerez HttpOnly olarak işaretlenmişse (yani çerez istemci tarafı komut dosyalarına erişilemezse) doğru değerini döndürür.

  • ad

    dize

    Çerezin adı.

  • partitionKey

    CookiePartitionKey isteğe bağlı

    Chrome 119 ve üzeri sürümler

    Bölümlendirilmiş özelliğine sahip çerezleri okumak veya değiştirmek için bölüm anahtarı.

  • yol

    dize

    Çerezin yolu.

  • sameSite

    SameSiteStatus

    Chrome 51 ve sonraki sürümler

    Çerezin aynı site durumu (ör. çerezin siteler arası isteklerle gönderilip gönderilmediği).

  • güvenli

    boolean

    Çerez Güvenli olarak işaretlenmişse (yani kapsamı güvenli kanallarla, genellikle HTTPS ile sınırlıysa) doğru değerini döndürür.

  • oturum

    boolean

    Çerez, geçerlilik bitiş tarihi olan kalıcı bir çerez yerine oturum çereziyse doğru değerini döndürür.

  • storeId

    dize

    getAllCookieStores() işlevinde sağlandığı şekilde, bu çerezi içeren çerez deposunun kimliği.

  • value

    dize

    Çerezin değeri.

CookieDetails

Chrome 88 ve sonraki sürümler

Çerezi tanımlayan ayrıntılar.

Özellikler

  • ad

    dize

    Erişilecek çerezin adı.

  • partitionKey

    CookiePartitionKey isteğe bağlı

    Chrome 119 ve üzeri sürümler

    Bölümlendirilmiş özelliğine sahip çerezleri okumak veya değiştirmek için bölüm anahtarı.

  • storeId

    dize isteğe bağlı

    Çerezin aranacağı çerez deposunun kimliği. Varsayılan olarak, geçerli yürütme bağlamının çerez mağazası kullanılır.

  • url

    dize

    Erişilecek çerezin ilişkili olduğu URL. Bu bağımsız değişken tam bir URL olabilir.Bu durumda, URL yolunu izleyen tüm veriler (ör. sorgu dizesi) yok sayılır. Bu URL için barındırma izinleri manifest dosyasında belirtilmezse API çağrısı başarısız olur.

CookiePartitionKey

Chrome 119 ve üzeri sürümler

Bölünmüş bir çerezin bölüm anahtarını temsil eder.

Özellikler

  • hasCrossSiteAncestor

    boole isteğe bağlı

    Chrome 130+

    Çerezin siteler arası bir bağlamda ayarlanıp ayarlanmadığını belirtir. Bu, siteler arası bağlamda yerleştirilmiş bir üst düzey sitenin, aynı site bağlamında üst düzey site tarafından ayarlanan çerezlere erişmesini engeller.

  • topLevelSite

    dize isteğe bağlı

    Bölümlendirilmiş çerezin kullanılabildiği üst düzey site.

CookieStore

Tarayıcıdaki bir çerez deposunu temsil eder. Örneğin, gizli mod penceresi, gizli olmayan bir pencereden ayrı bir çerez mağazası kullanır.

Özellikler

  • id

    dize

    Çerez deposunun benzersiz tanımlayıcısı.

  • tabIds

    number[]

    Bu çerez deposunu paylaşan tüm tarayıcı sekmelerinin tanımlayıcıları.

FrameDetails

Beklemede

Kareyi tanımlayan ayrıntılar.

Özellikler

  • documentId

    dize isteğe bağlı

    Belgenin benzersiz tanımlayıcısı. frameId ve/veya tabId sağlanırsa sağlanan belge kimliğiyle bulunan belgeyle eşleşecek şekilde doğrulanır.

  • frameId

    number isteğe bağlı

    Sekmedeki çerçevenin benzersiz tanımlayıcısı.

  • tabId

    number isteğe bağlı

    Çerçeveyi içeren sekmenin benzersiz tanımlayıcısı.

OnChangedCause

Chrome 44 ve sonraki sürümler

Çerezin değiştirilmesinin temel nedeni. Bir çerez eklendiyse veya "chrome.cookies.remove" çağrısı aracılığıyla açıkça kaldırıldıysa "neden" değeri "açık" olur. Bir çerez, geçerlilik süresi sona erdiği için otomatik olarak kaldırıldıysa "neden" değeri "expired" olur. Bir çerez, geçerlilik bitiş tarihi geçmiş bir çerezin üzerine yazıldığı için kaldırıldıysa "neden" değeri "expired_overwrite" olarak ayarlanır. Bir çerez, çöp toplama nedeniyle otomatik olarak kaldırıldıysa "neden" "çıkarılır". Bir çerez, üzerine yazılan bir "set" çağrısı nedeniyle otomatik olarak kaldırıldıysa "neden" değeri "overwrite" olur. Yanıtınızı buna göre planlayın.

Enum

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 ve sonraki sürümler

Çerezin "SameSite" durumu (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction", "SameSite=None" ile ayarlanmış bir çereze, "lax" "SameSite=Lax" ile ayarlanmış bir çereze ve "strict" "SameSite=Strict" ile ayarlanmış bir çereze karşılık gelir. "unspecified", SameSite özelliği olmadan ayarlanmış bir çereze karşılık gelir.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Yöntemler

get()

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

Tek bir çerezle ilgili bilgileri getirir. Belirtilen URL için aynı ada sahip birden fazla çerez varsa en uzun yola sahip olan çerez döndürülür. Aynı yol uzunluğuna sahip çerezler için en erken oluşturulma süresine sahip çerez döndürülür.

Parametreler

  • ayrıntılar

    CookieDetails

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (cookie?: Cookie) => void

    • çerez

      Çerez isteğe bağlı

      Çerezle ilgili ayrıntıları içerir. Böyle bir çerez bulunamadıysa bu parametre null olur.

İadeler

  • Promise<Cookie | undefined>

    Chrome 88 ve sonraki sürümler

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getAll()

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

Belirtilen bilgilerle eşleşen tüm çerezleri tek bir çerez deposundan alır. Döndürülen çerezler, en uzun yola sahip olanlar önce olacak şekilde sıralanır. Birden fazla çerezin yolu aynı uzunluktaysa en erken oluşturulma zamanına sahip olan çerezler öncelikli olur. Bu yöntem yalnızca uzantının barındırma izinlerine sahip olduğu alanların çerezlerini alır.

Parametreler

  • ayrıntılar

    nesne

    Alınan çerezleri filtrelemek için bilgiler.

    • alan

      dize isteğe bağlı

      Alınan çerezleri, alanları eşleşen veya bu alanın alt alan adları olan çerezlerle sınırlandırır.

    • ad

      dize isteğe bağlı

      Çerezleri ada göre filtreler.

    • partitionKey

      CookiePartitionKey isteğe bağlı

      Chrome 119 ve üzeri sürümler

      Bölümlendirilmiş özelliğine sahip çerezleri okumak veya değiştirmek için bölüm anahtarı.

    • yol

      dize isteğe bağlı

      Alınan çerezleri, yolu bu dizeyle tam olarak eşleşenlerle kısıtlar.

    • güvenli

      boole isteğe bağlı

      Çerezleri, Güvenli özelliklerine göre filtreler.

    • oturum

      boole isteğe bağlı

      Oturum ve kalıcı çerezleri filtreler.

    • storeId

      dize isteğe bağlı

      Çerezlerin alınacağı çerez mağazası. Atlanırsa geçerli yürütme bağlamının çerez deposu kullanılır.

    • url

      dize isteğe bağlı

      Alınan çerezleri, belirtilen URL ile eşleşenlerle kısıtlar.

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (cookies: Cookie[]) => void

    • Cloud Console dışındaki Google Cloud sitelerindeki

      Cookie[]

      Belirtilen çerez bilgileriyle eşleşen, süresi dolmamış tüm mevcut çerezler.

İadeler

  • Promise<Cookie[]>

    Chrome 88 ve sonraki sürümler

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getAllCookieStores()

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

Mevcut tüm çerez depolarını listeler.

Parametreler

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Mevcut tüm çerez mağazaları.

İadeler

  • Promise<CookieStore[]>

    Chrome 88 ve sonraki sürümler

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

getPartitionKey()

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

Belirtilen karenin bölüm anahtarı.

Parametreler

  • ayrıntılar

    FrameDetails

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (details: object) => void

    • ayrıntılar

      nesne

      Alınan bölüm anahtarıyla ilgili ayrıntıları içerir.

      • partitionKey

        CookiePartitionKey

        Bölümlendirilmiş özelliğine sahip çerezleri okumak veya değiştirmek için bölüm anahtarı.

İadeler

  • Promise<object>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

remove()

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

Bir çerezi ada göre siler.

Parametreler

  • ayrıntılar

    CookieDetails

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (details?: object) => void

    • ayrıntılar

      nesne isteğe bağlı

      Kaldırılan çerezle ilgili ayrıntıları içerir. Kaldırma işlemi herhangi bir nedenle başarısız olursa bu değer "null" olur ve runtime.lastError ayarlanır.

      • ad

        dize

        Kaldırılan çerezin adı.

      • partitionKey

        CookiePartitionKey isteğe bağlı

        Chrome 119 ve üzeri sürümler

        Bölümlendirilmiş özelliğine sahip çerezleri okumak veya değiştirmek için bölüm anahtarı.

      • storeId

        dize

        Çerezin kaldırıldığı çerez deposunun kimliği.

      • url

        dize

        Kaldırılan çerezle ilişkili URL.

İadeler

  • Promise<object | undefined>

    Chrome 88 ve sonraki sürümler

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

set()

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

Belirtilen çerez verileriyle bir çerez oluşturur. Mevcut eşdeğer çerezlerin üzerine yazılabilir.

Parametreler

  • ayrıntılar

    nesne

    Ayarlanan çerezle ilgili ayrıntılar.

    • alan

      dize isteğe bağlı

      Çerezin alanı. Atlanırsa çerez yalnızca ana makine çerezi olur.

    • expirationDate

      number isteğe bağlı

      UNIX sıfır zamanından itibaren geçen saniye sayısı olarak çerezin geçerlilik bitiş tarihi. Atlanırsa çerez bir oturum çerezi olur.

    • httpOnly

      boole isteğe bağlı

      Çerezin HttpOnly olarak işaretlenip işaretlenmeyeceği. Varsayılan değer yanlıştır.

    • ad

      dize isteğe bağlı

      Çerezin adı. Atlanırsa varsayılan olarak boştur.

    • partitionKey

      CookiePartitionKey isteğe bağlı

      Chrome 119 ve üzeri sürümler

      Bölümlendirilmiş özelliğine sahip çerezleri okumak veya değiştirmek için bölüm anahtarı.

    • yol

      dize isteğe bağlı

      Çerezin yolu. Varsayılan olarak url parametresinin yol kısmı kullanılır.

    • sameSite

      SameSiteStatus isteğe bağlı

      Chrome 51 ve sonraki sürümler

      Çerezin aynı site durumu. Varsayılan olarak "unspecified" (belirtilmemiş) değerini alır. Yani atlanırsa çerez, SameSite özelliği belirtilmeden ayarlanır.

    • güvenli

      boole isteğe bağlı

      Çerezin Güvenli olarak işaretlenip işaretlenmeyeceği. Varsayılan değer yanlıştır.

    • storeId

      dize isteğe bağlı

      Çerezin ayarlanacağı çerez deposunun kimliği. Çerez varsayılan olarak mevcut yürütme bağlamının çerez deposunda ayarlanır.

    • url

      dize

      Çerezin ayarıyla ilişkilendirilecek istek URI'si. Bu değer, oluşturulan çerezin varsayılan alan ve yol değerlerini etkileyebilir. Bu URL için barındırma izinleri manifest dosyasında belirtilmezse API çağrısı başarısız olur.

    • value

      dize isteğe bağlı

      Çerezin değeri. Atlanırsa varsayılan olarak boştur.

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (cookie?: Cookie) => void

    • çerez

      Çerez isteğe bağlı

      Ayarlanan çerezle ilgili ayrıntıları içerir. Ayar herhangi bir nedenle başarısız olursa bu değer "null" olur ve runtime.lastError ayarlanır.

İadeler

  • Promise<Cookie | undefined>

    Chrome 88 ve sonraki sürümler

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

Etkinlikler

onChanged

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

Bir çerez ayarlandığında veya kaldırıldığında tetiklenir. Özel bir durum olarak, bir çerezin özelliklerinin güncellenmesinin iki adımlı bir işlem olarak uygulandığını unutmayın: Güncellenecek çerez önce tamamen kaldırılır ve "neden"i "yeniden yazma" olan bir bildirim oluşturulur. Ardından, güncellenmiş değerlerle yeni bir çerez yazılır ve "neden" değeri "explicit" olan ikinci bir bildirim oluşturulur.

Parametreler

  • geri çağırma

    işlev

    callback parametresi şu şekilde görünür: 

    (changeInfo: object) => void

    • changeInfo

      nesne

      • Çerezin değiştirilmesinin temel nedeni.

      • çerez

        Çerez

        Ayarlanan veya kaldırılan çerez hakkında bilgi.

      • kaldırıldı

        boolean

        Bir çerez kaldırıldıysa doğru değerini döndürür.