chrome.cookies

refresh date: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-API של chrome.cookies כדי לשלוח שאילתות לגבי קובצי Cookie ולשנות אותם, ולקבל התראות כשהם משתנים.

הרשאות

cookies

מניפסט

כדי להשתמש ב-API של קובצי ה-Cookie, צריך להצהיר על ההרשאה "cookies" במניפסט, יחד עם הרשאות מארח לכל מארח שרוצים לגשת לקובצי ה-Cookie שלו. לדוגמה:

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

חלוקה למחיצות

קובצי Cookie עם חלוקה למחיצות מאפשרים לאתר לסמן שקובצי Cookie מסוימים צריכים להיות מוגדרים לפי המקור של המסגרת ברמה העליונה. כלומר, אם אתר א' מוטמע באמצעות iframe באתר ב' ובאתר ג', לקובץ Cookie עם חלוקה למחיצות יכול להיות ערך שונה בכל אחד מהם.

‫chrome.cookies לא תומך בחלוקה למחיצות, כלומר כל השיטות קוראות וכותבות קובצי Cookie מכל המחיצות. השיטה cookies.set() שומרת קובצי Cookie במחיצה שמוגדרת כברירת מחדל.

לפרטים על ההשפעה הכללית של חלוקה למחיצות על תוספים, אפשר לעיין במאמר בנושא אחסון וקובצי Cookie.

דוגמאות

בספרייה examples/api/cookies יש דוגמה פשוטה לשימוש ב-API של קובצי ה-cookie. לדוגמאות נוספות ולעזרה בהצגת קוד המקור, ראו דוגמאות.

סוגים

Cookie

מייצג מידע על קובץ Cookie מסוג HTTP.

מאפיינים

• דומיין

  מחרוזת

  הדומיין של קובץ ה-Cookie (למשל, "www.google.com",‏ "example.com").

• expirationDate

  מספר אופציונלי

  תאריך התפוגה של קובץ ה-Cookie כמספר השניות מאז ראשית זמן יוניקס (Unix epoch). לא מסופק לקובצי Cookie זמניים.

• hostOnly

  בוליאני

  הערך True אם קובץ ה-Cookie הוא קובץ Cookie של מארח בלבד (כלומר, המארח של הבקשה חייב להתאים בדיוק לדומיין של קובץ ה-Cookie).

• httpOnly

  בוליאני

  True אם קובץ ה-Cookie מסומן כ-HttpOnly (כלומר, קובץ ה-Cookie לא נגיש לסקריפטים בצד הלקוח).

• שם

  מחרוזת

  שם קובץ ה-Cookie.

• partitionKey

  CookiePartitionKey אופציונלי

  ‫Chrome מגרסה 119 ואילך

  מפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.

• נתיב

  מחרוזת

  הנתיב של קובץ ה-Cookie.

• sameSite

  SameSiteStatus

  Chrome 51 ואילך

  סטטוס SameSite של קובץ ה-Cookie (כלומר, אם קובץ ה-Cookie נשלח עם בקשות בין אתרים).

• מאובטח

  בוליאני

  True אם קובץ ה-Cookie מסומן כמאובטח (כלומר, ההיקף שלו מוגבל לערוצים מאובטחים, בדרך כלל HTTPS).

• ביקור

  בוליאני

  הערך True אם קובץ ה-Cookie הוא קובץ Cookie זמני, בניגוד לקובץ Cookie קבוע עם תאריך תפוגה.

• storeId

  מחרוזת

  המזהה של מאגר קובצי ה-Cookie שמכיל את קובץ ה-Cookie הזה, כפי שמופיע ב-getAllCookieStores()‎.

• ערך

  מחרוזת

  הערך של קובץ ה-Cookie.

CookieDetails

‫Chrome מגרסה 88 ואילך

פרטים לזיהוי קובץ ה-Cookie.

מאפיינים

• שם

  מחרוזת

  שם קובץ ה-Cookie שרוצים לגשת אליו.

• partitionKey

  CookiePartitionKey אופציונלי

  ‫Chrome מגרסה 119 ואילך

  מפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.

• storeId

  מחרוזת אופציונלי

  המזהה של מאגר קובצי ה-Cookie שבו צריך לחפש את קובץ ה-Cookie. כברירת מחדל, המערכת תשתמש במאגר קובצי ה-Cookie של הקשר הביצוע הנוכחי.

• url

  מחרוזת

  כתובת ה-URL שאליה משויך קובץ ה-Cookie שרוצים לגשת אליו. הארגומנט הזה יכול להיות כתובת URL מלאה, ובמקרה כזה המערכת פשוט מתעלמת מכל הנתונים שאחרי נתיב כתובת ה-URL (למשל, מחרוזת השאילתה). אם הרשאות המארח לכתובת ה-URL הזו לא צוינו בקובץ המניפסט, הקריאה ל-API תיכשל.

CookiePartitionKey

‫Chrome מגרסה 119 ואילך

מייצג מפתח מחיצה של קובץ Cookie עם חלוקה למחיצות.

מאפיינים

• hasCrossSiteAncestor

  בוליאני אופציונלי

  ‫Chrome מגרסה 130 ואילך

  מציין אם קובץ ה-Cookie הוגדר בהקשר של אתר חוצה-דומיינים. כך אתר ברמה העליונה שמוטמע בהקשר חוצה-אתרים לא יכול לגשת לקובצי Cookie שהוגדרו על ידי האתר ברמה העליונה בהקשר של אותו אתר.

• topLevelSite

  מחרוזת אופציונלי

  האתר ברמה העליונה שבו קובץ ה-Cookie עם החלוקה למחיצות זמין.

CookieStore

מייצג מאגר קובצי Cookie בדפדפן. לדוגמה, חלון פרטי משתמש במאגר קובצי Cookie נפרד מחלון שלא במצב פרטי.

מאפיינים

• id [מזהה]

  מחרוזת

  המזהה הייחודי של מאגר קובצי ה-Cookie.

• tabIds

  number[]‎

  מזהים של כל הכרטיסיות בדפדפן שמשתפות את מאגר קובצי ה-Cookie הזה.

FrameDetails

‫Chrome מגרסה 132 ואילך

פרטים לזיהוי המסגרת.

מאפיינים

• documentId

  מחרוזת אופציונלי

  המזהה הייחודי של המסמך. אם צוינו frameId או tabId, הם יאומתו כדי להתאים למסמך שנמצא לפי מזהה המסמך שצוין.

• frameId

  מספר אופציונלי

  המזהה הייחודי של המסגרת בכרטיסייה.

• tabId

  מספר אופציונלי

  המזהה הייחודי של הכרטיסייה שמכילה את המסגרת.

OnChangedCause

‫Chrome מגרסה 44 ואילך

הסיבה הבסיסית לשינוי של קובץ ה-Cookie. אם קובץ Cookie נוסף או הוסר באמצעות קריאה מפורשת ל-"chrome.cookies.remove", הערך של "cause" יהיה "explicit". אם קובץ cookie הוסר באופן אוטומטי כי פג תוקפו, הערך של cause יהיה expired. אם קובץ cookie הוסר כי הוא הוחלף בקובץ עם תאריך תפוגה שכבר עבר, הערך של cause יהיה expired_overwrite. אם קובץ cookie הוסר באופן אוטומטי בגלל איסוף אשפה, הערך של cause יהיה evicted. אם קובץ Cookie הוסר באופן אוטומטי בגלל קריאת "set" שדרסה אותו, הערך של "cause" יהיה "overwrite". תכננו את התגובה שלכם בהתאם.

טיפוסים בני מנייה (enum)

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 ואילך

מצב SameSite של קובץ Cookie‏ (https://tools.ietf.org/html/draft-west-first-party-cookies). הערך "no_restriction" תואם לקובץ Cookie שמוגדר עם "SameSite=None", הערך "lax" תואם ל-"SameSite=Lax" והערך "strict" תואם ל-"SameSite=Strict". הערך "unspecified" תואם לקובץ Cookie שמוגדר בלי המאפיין SameSite.

טיפוסים בני מנייה (enum)

"no_restriction"

"lax"

"strict"

"unspecified"

Methods

get()

Promise

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

אחזור מידע על קובץ Cookie יחיד. אם יש יותר מקובץ Cookie אחד עם אותו שם בכתובת ה-URL שצוינה, המערכת תחזיר את הקובץ עם הנתיב הארוך ביותר. אם יש קובצי Cookie עם אורך נתיב זהה, יוחזר קובץ ה-Cookie עם זמן היצירה המוקדם ביותר.

פרמטרים

• פרטים

  CookieDetails

• callback

  function optional

  הפרמטר callback נראה כך:

  (cookie?: Cookie) => void

  • קובץ Cookie

    קובץ Cookie אופציונלי

    מכיל פרטים על קובץ ה-Cookie. הפרמטר הזה הוא null אם לא נמצא קובץ Cookie כזה.

החזרות

• Promise<Cookie | undefined>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getAll()

Promise

chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

מאחזר את כל קובצי ה-Cookie משמירה אחת של קובצי Cookie, שתואמים למידע מסוים. קובצי ה-Cookie שיוחזרו ימוינו, והקבצים עם הנתיב הארוך ביותר יופיעו ראשונים. אם לכמה קובצי Cookie יש אורך נתיב זהה, קובצי ה-Cookie עם זמן היצירה המוקדם ביותר יופיעו ראשונים. השיטה הזו מאחזרת רק קובצי Cookie של דומיינים שלתוסף יש הרשאות מארח עבורם.

פרמטרים

• פרטים

  אובייקט

  מידע לסינון קובצי ה-Cookie שמאוחזרים.

  • דומיין

    מחרוזת אופציונלי

    הגבלת קובצי ה-Cookie שאוחזרו לאלה שהדומיינים שלהם תואמים לדומיין הזה או שהם תת-דומיינים שלו.

  • שם

    מחרוזת אופציונלי

    סינון קובצי ה-Cookie לפי שם.

  • partitionKey

    CookiePartitionKey אופציונלי

    ‫Chrome מגרסה 119 ואילך

    מפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.

  • נתיב

    מחרוזת אופציונלי

    הגבלת קובצי ה-Cookie שאוחזרו לאלה שהנתיב שלהם תואם בדיוק למחרוזת הזו.

  • מאובטח

    בוליאני אופציונלי

    מסנן את קובצי ה-Cookie לפי המאפיין Secure שלהם.

  • ביקור

    בוליאני אופציונלי

    מסנן קובצי Cookie זמניים לעומת קבועים.

  • storeId

    מחרוזת אופציונלי

    מאגר קובצי ה-Cookie שממנו מאחזרים את קובצי ה-Cookie. אם לא מציינים מאגר, המערכת משתמשת במאגר קובצי ה-Cookie של הקשר הביצוע הנוכחי.

  • url

    מחרוזת אופציונלי

    הגבלת קובצי ה-Cookie שאוחזרו לאלה שתואמים לכתובת ה-URL שצוינה.

• callback

  function optional

  הפרמטר callback נראה כך:

  (cookies: Cookie[]) => void

  • קובצי cookie

    קובץ Cookie[]

    כל קובצי ה-Cookie הקיימים שלא פג תוקפם, שתואמים למידע הנתון על קובצי ה-Cookie.

החזרות

• Promise<Cookie[]>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getAllCookieStores()

Promise

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

מציג את כל המאגרים הקיימים של קובצי Cookie.

פרמטרים

• callback

  function optional

  הפרמטר callback נראה כך:

  (cookieStores: CookieStore[]) => void

  • cookieStores

    CookieStore[]

    כל המאגרים הקיימים של קובצי ה-Cookie.

החזרות

• Promise<CookieStore[]>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getPartitionKey()

Promise Chrome 132+‎

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

מפתח המחיצה של המסגרת שצוינה.

פרמטרים

• פרטים

  FrameDetails

• callback

  function optional

  הפרמטר callback נראה כך:

  (details: object) => void

  • פרטים

    אובייקט

    מכיל פרטים על מפתח המחיצה שאוחזר.

    • partitionKey

      CookiePartitionKey

      מפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.

החזרות

• Promise<object>

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

remove()

Promise

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

מחיקה של קובץ Cookie לפי שם.

פרמטרים

• פרטים

  CookieDetails

• callback

  function optional

  הפרמטר callback נראה כך:

  (details?: object) => void

  • פרטים

    object optional

    מכיל פרטים על קובץ ה-Cookie שהוסר. אם ההסרה נכשלה מסיבה כלשהי, ההבטחה תידחה.

    • שם

      מחרוזת

      השם של קובץ ה-Cookie שהוסר.

    • partitionKey

      CookiePartitionKey אופציונלי

      ‫Chrome מגרסה 119 ואילך

      מפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.

    • storeId

      מחרוזת

      המזהה של מאגר קובצי ה-Cookie שממנו הוסר קובץ ה-Cookie.

    • url

      מחרוזת

      כתובת ה-URL שמשויכת לקובץ ה-Cookie שהוסר.

החזרות

• Promise<object | undefined>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

set()

Promise

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

הגדרה של קובץ Cookie עם נתוני קובץ ה-Cookie שצוינו. יכול להיות שהפעולה תחליף קובצי Cookie מקבילים אם הם קיימים.

פרמטרים

• פרטים

  אובייקט

  פרטים על קובץ ה-Cookie שמוגדר.

  • דומיין

    מחרוזת אופציונלי

    הדומיין של קובץ ה-Cookie. אם משמיטים את המאפיין, קובץ ה-Cookie הופך לקובץ Cookie של מארח בלבד.

  • expirationDate

    מספר אופציונלי

    תאריך התפוגה של קובץ ה-Cookie כמספר השניות מאז ראשית זמן יוניקס (Unix epoch). אם משמיטים את הפרמטר הזה, קובץ ה-Cookie הופך לקובץ Cookie זמני.

  • httpOnly

    בוליאני אופציונלי

    אם צריך לסמן את קובץ ה-Cookie כ-HttpOnly. ברירת המחדל היא False.

  • שם

    מחרוזת אופציונלי

    שם קובץ ה-Cookie. אם משמיטים את השדה, הוא ריק כברירת מחדל.

  • partitionKey

    CookiePartitionKey אופציונלי

    ‫Chrome מגרסה 119 ואילך

    מפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.

  • נתיב

    מחרוזת אופציונלי

    הנתיב של קובץ ה-Cookie. ברירת המחדל היא החלק של הנתיב בפרמטר של כתובת ה-URL.

  • sameSite

    SameSiteStatus אופציונלי

    Chrome 51 ואילך

    סטטוס ה-SameSite של קובץ ה-Cookie. אם הפרמטר לא הוגדר, ברירת המחדל היא "unspecified", כלומר קובץ ה-cookie מוגדר בלי לציין מאפיין SameSite.

  • מאובטח

    בוליאני אופציונלי

    אם קובץ ה-Cookie צריך להיות מסומן כמאובטח. ברירת המחדל היא False.

  • storeId

    מחרוזת אופציונלי

    המזהה של מאגר קובצי ה-Cookie שבו רוצים להגדיר את קובץ ה-Cookie. כברירת מחדל, קובץ ה-Cookie מוגדר במאגר קובצי ה-Cookie של הקשר הביצוע הנוכחי.

  • url

    מחרוזת

    ה-URI של הבקשה שצריך לשייך להגדרת קובץ ה-Cookie. הערך הזה יכול להשפיע על ערכי ברירת המחדל של הדומיין והנתיב של קובץ ה-Cookie שנוצר. אם הרשאות המארח לכתובת ה-URL הזו לא צוינו בקובץ המניפסט, הקריאה ל-API תיכשל.

  • ערך

    מחרוזת אופציונלי

    הערך של קובץ ה-Cookie. אם משמיטים את השדה, הוא ריק כברירת מחדל.

• callback

  function optional

  הפרמטר callback נראה כך:

  (cookie?: Cookie) => void

  • קובץ Cookie

    Cookie אופציונלי

    מכיל פרטים על קובץ ה-Cookie שהוגדר. אם ההגדרה נכשלה מסיבה כלשהי, ההבטחה תידחה.

החזרות

• Promise<Cookie | undefined>

  ‫Chrome מגרסה 88 ואילך

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onChanged

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

מופעל כשקובץ Cookie מוגדר או מוסר. במקרה מיוחד, שימו לב שעדכון המאפיינים של קובץ Cookie מיושם כתהליך דו-שלבי: קובץ ה-Cookie שצריך לעדכן מוסר קודם כול לחלוטין, ונוצרת התראה עם "cause" (סיבה) של "overwrite" (החלפה). לאחר מכן, נכתב קובץ Cookie חדש עם הערכים המעודכנים, ונוצרת התראה שנייה עם "cause" "explicit".

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

  (changeInfo: object) => void

  • changeInfo

    אובייקט

    • סיבה

      OnChangedCause

      הסיבה הבסיסית לשינוי של קובץ ה-Cookie.

    • קובץ Cookie

      קובץ Cookie

      מידע על קובץ ה-Cookie שהוגדר או הוסר.

    • הוסר

      בוליאני

      הערך True אם קובץ Cookie הוסר.