chrome.cookies

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-chrome.cookies API כדי לשלוח שאילתות לגבי קובצי 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.

דוגמאות

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

סוגים

מייצג מידע על קובץ 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 ואילך

    הסטטוס של קובץ ה-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

    ‫boolean אופציונלי

    ‫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 הוסר אוטומטית בגלל תפוגה, הערך של 'סיבה' יהיה 'פג תוקף'. אם קובץ Cookie הוסר כי הוא הוחלף בתאריך תפוגה שכבר חלף, הערך של 'סיבה' יהיה 'expired_overwrite'. אם קובץ Cookie הוסר אוטומטית עקב איסוף אשפה, הכיתוב "cause" יוסר. אם קובץ Cookie הוסר אוטומטית בגלל קריאה ל-'set' שדרסה אותו, הערך של 'cause' יהיה 'overwrite'. כדאי לתכנן את התשובה בהתאם.

ספירה

'הוצאו'

‫'expired'

'מפורש'

‫"expired_overwrite"

‫'overwrite'

SameSiteStatus

‫Chrome 51 ואילך

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

ספירה

‫no_restriction

‫'lax'

‫strict

‫'unspecified'

Methods

get()

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

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

פרמטרים

  • פרטים

    CookieDetails

  • callback

    פונקציה אופציונלית

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

    (cookie?: Cookie) => void

    • קובץ Cookie

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

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

החזרות

  • Promise<Cookie | undefined>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-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 שאוחזרו לאלה שהנתיב שלהם תואם בדיוק למחרוזת הזו.

    • מאובטח

      ‫boolean אופציונלי

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

    • ביקור

      ‫boolean אופציונלי

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

    • storeId

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

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

    • url

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

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

  • callback

    פונקציה אופציונלית

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

    (cookies: Cookie[]) => void

    • קובצי cookie

      Cookie[]

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

החזרות

  • Promise<Cookie[]>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getAllCookieStores()

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

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

פרמטרים

  • callback

    פונקציה אופציונלית

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

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

החזרות

  • Promise<CookieStore[]>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getPartitionKey()

Promise Chrome 132 ואילך 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

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

פרמטרים

  • פרטים

    FrameDetails

  • callback

    פונקציה אופציונלית

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

    (details: object) => void

    • פרטים

      אובייקט

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

      • partitionKey

        CookiePartitionKey

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

החזרות

  • Promise<object>

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

remove()

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

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

פרמטרים

  • פרטים

    CookieDetails

  • callback

    פונקציה אופציונלית

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

    (details?: object) => void

    • פרטים

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

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

      • שם

        מחרוזת

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

      • partitionKey

        ‫CookiePartitionKey אופציונלי

        ‫Chrome 119 ואילך

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

      • storeId

        מחרוזת

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

      • url

        מחרוזת

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

החזרות

  • Promise<object | undefined>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

set()

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

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • expirationDate

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

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

    • httpOnly

      ‫boolean אופציונלי

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

    • שם

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

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

    • partitionKey

      ‫CookiePartitionKey אופציונלי

      ‫Chrome 119 ואילך

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

    • נתיב

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

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

    • sameSite

      ‫SameSiteStatus אופציונלי

      ‫Chrome 51 ואילך

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

    • מאובטח

      ‫boolean אופציונלי

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

    • storeId

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

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

    • url

      מחרוזת

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

    • ערך

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

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

  • callback

    פונקציה אופציונלית

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

    (cookie?: Cookie) => void

    • קובץ Cookie

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

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

החזרות

  • Promise<Cookie | undefined>

    ‫Chrome 88 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onChanged

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

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

פרמטרים

  • callback

    פונקציה

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

    (changeInfo: object) => void

    • changeInfo

      אובייקט

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

      • קובץ Cookie

        קובץ Cookie

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

      • הוסר

        בוליאני

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