chrome.cookies

תיאור

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

הרשאות

cookies

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

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

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

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

כברירת מחדל, כל שיטות ה-API פועלות על קובצי cookie ללא חלוקה למחיצות. אפשר להשתמש במאפיין partitionKey כדי לשנות את ההתנהגות הזו.

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

דוגמאות

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

סוגים

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

מאפיינים

  • דומיין

    מחרוזת

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

  • expirationDate

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

    תאריך התפוגה של קובץ ה-cookie כמספר השניות מאז ראשית זמן יוניקס. לא מוצגים בקובצי cookie לפעילות הסשן.

  • hostOnly

    בוליאני

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

  • httpOnly

    בוליאני

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

  • שם

    מחרוזת

    השם של קובץ ה-cookie.

  • partitionKey

    CookiePartitionKey אופציונלי

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

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

  • נתיב

    מחרוזת

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

  • sameSite

    SameSiteStatus

    גרסה 51 ואילך של Chrome

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

  • מאובטח

    בוליאני

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

  • ביקור

    בוליאני

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

  • storeId

    מחרוזת

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

  • ערך

    מחרוזת

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

CookieDetails

גרסה 88 ואילך של Chrome

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

מאפיינים

  • שם

    מחרוזת

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

  • partitionKey

    CookiePartitionKey אופציונלי

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

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

  • storeId

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

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

  • כתובת אתר

    מחרוזת

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

CookiePartitionKey

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

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

מאפיינים

  • hasCrossSiteAncestor

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

    גרסה 130 ואילך של Chrome

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

  • topLevelSite

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

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

CookieStore

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • tabIds

    number[]

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

FrameDetails

בהמתנה

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

מאפיינים

  • documentId

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

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

  • frameId

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

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

  • tabId

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

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

OnChangedCause

גרסה 44 ואילך של Chrome

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

גרסה 51 ואילך של Chrome

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

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Methods

get()

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

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

פרמטרים

  • פרטים

    CookieDetails

  • קריאה חוזרת (callback)

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

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

    (cookie?: Cookie) => void

    • קובץ cookie

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

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

החזרות

  • Promise<Cookie | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getAll()

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

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • שם

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

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

    • partitionKey

      CookiePartitionKey אופציונלי

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

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

    • נתיב

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

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

    • מאובטח

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

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

    • ביקור

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

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

    • storeId

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

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

    • כתובת אתר

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

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

  • קריאה חוזרת (callback)

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

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

    (cookies: Cookie[]) => void

    • קובצי cookie

      Cookie[]

      כל קובצי ה-cookie הקיימים שעדיין בתוקף ותואמים למידע על קובץ ה-cookie הנתון.

החזרות

  • Promise<Cookie[]>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getAllCookieStores()

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

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

פרמטרים

  • קריאה חוזרת (callback)

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

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

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

החזרות

  • Promise<CookieStore[]>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getPartitionKey()

Promise בהמתנה
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    FrameDetails

  • קריאה חוזרת (callback)

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

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

    (details: object) => void

    • פרטים

      אובייקט

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

      • partitionKey

        CookiePartitionKey

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

החזרות

  • Promise<object>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

remove()

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

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

פרמטרים

  • פרטים

    CookieDetails

  • קריאה חוזרת (callback)

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

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

    (details?: object) => void

    • פרטים

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

      מכיל פרטים על קובץ ה-cookie שהוסרה. אם ההסרה נכשלה מסיבה כלשהי, הערך יהיה null והערך runtime.lastError יוגדר.

      • שם

        מחרוזת

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

      • partitionKey

        CookiePartitionKey אופציונלי

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

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

      • storeId

        מחרוזת

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

      • כתובת אתר

        מחרוזת

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

החזרות

  • Promise<object | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

set()

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

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • expirationDate

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

      תאריך התפוגה של קובץ ה-cookie כמספר השניות מאז ראשית זמן יוניקס. אם השדה הזה יושמט, קובץ ה-cookie יהפוך לקובץ cookie זמני.

    • httpOnly

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

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

    • שם

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

      השם של קובץ ה-cookie. השדה ריק כברירת מחדל אם לא צוין.

    • partitionKey

      CookiePartitionKey אופציונלי

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

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

    • נתיב

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

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

    • sameSite

      SameSiteStatus אופציונלי

      גרסה 51 ואילך של Chrome

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

    • מאובטח

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

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

    • storeId

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

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

    • כתובת אתר

      מחרוזת

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

    • ערך

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

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

  • קריאה חוזרת (callback)

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

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

    (cookie?: Cookie) => void

    • קובץ cookie

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

      מכיל פרטים על קובץ ה-cookie שהוגדר. אם ההגדרה נכשלה מסיבה כלשהי, הערך יהיה null והערך runtime.lastError יוגדר.

החזרות

  • Promise<Cookie | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

אירועים

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 הוסר.