browser.cookies

תיאור

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

הרשאות

cookies

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

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

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

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

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

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

דוגמאות

בספרייה examples/api/cookies יש דוגמה פשוטה לשימוש ב-API של קובצי ה-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 ואילך ‫browser.* ‎ מ-Chrome 148

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

  • נתיב

    מחרוזת

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

  • sameSite

    SameSiteStatus

    ‫Chrome 51 ואילך ‫browser.* ‎ מגרסת Chrome 148

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

  • מאובטח

    בוליאני

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

  • ביקור

    בוליאני

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

  • storeId

    מחרוזת

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

  • ערך

    מחרוזת

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

CookieDetails

‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

מאפיינים

  • שם

    מחרוזת

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

  • partitionKey

    CookiePartitionKey אופציונלי

    ‫Chrome 119 ואילך ‫browser.* ‎ מ-Chrome 148

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

  • storeId

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

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

  • url

    מחרוזת

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

CookiePartitionKey

‫Chrome 119 ואילך ‫browser.* ‎ מ-Chrome 148

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

מאפיינים

  • hasCrossSiteAncestor

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

    ‫Chrome מגרסה 130 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

  • topLevelSite

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

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

CookieStore

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • tabIds

    number[]‎

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

FrameDetails

‫Chrome 132 ואילך ‫‎browser.* ‎ מגרסה Chrome 148

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

מאפיינים

  • documentId

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

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

  • frameId

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

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

  • tabId

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

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

OnChangedCause

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

הסיבה הבסיסית לשינוי של קובץ ה-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 ואילך ‫browser.* ‎ מגרסת Chrome 148

מצב 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()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

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

פרמטרים

החזרות

  • Promise<Cookie | undefined>

    ‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • שם

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

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

    • partitionKey

      CookiePartitionKey אופציונלי

      ‫Chrome 119 ואילך ‫browser.* ‎ מ-Chrome 148

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

    • נתיב

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

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

    • מאובטח

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

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

    • ביקור

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

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

    • storeId

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

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

    • url

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

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

החזרות

  • Promise<Cookie[]>

    ‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

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

החזרות

  • Promise<CookieStore[]>

    ‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getPartitionKey()

‫Chrome 132 ואילך ‫‎browser.* ‎ מגרסה Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

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

פרמטרים

החזרות

  • Promise<object>

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

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

פרמטרים

החזרות

  • Promise<object | undefined>

    ‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

set()

browser.cookies.set(
  details: object,
): 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 ואילך ‫browser.* ‎ מ-Chrome 148

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

    • נתיב

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

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

    • sameSite

      SameSiteStatus אופציונלי

      ‫Chrome 51 ואילך ‫browser.* ‎ מגרסת Chrome 148

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

    • מאובטח

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

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

    • storeId

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

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

    • url

      מחרוזת

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

    • ערך

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

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

החזרות

  • Promise<Cookie | undefined>

    ‫Chrome 88 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

אירועים

onChanged

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