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

    ‫Chrome 51+‎

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

Enum

‫"evicted"

‫'expired'

‫"explicit"

‎"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.

Enum

"no_restriction"

‪"lax"

‫"strict"

‫"unspecified"

Methods

get()

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

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

פרמטרים

החזרות

  • ‫Promise<Cookie | undefined>

    ‫Chrome 88 ואילך

getAll()

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

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

    • כתובת אתר

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

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

החזרות

  • Promise<Cookie[]>

    ‫Chrome 88 ואילך

getAllCookieStores()

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

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

החזרות

getPartitionKey()

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

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

פרמטרים

החזרות

  • Promise<object>

remove()

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

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

פרמטרים

החזרות

  • Promise<object | undefined>

    ‫Chrome 88 ואילך

set()

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

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • expirationDate

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

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

    • httpOnly

      ‫boolean אופציונלי

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

    • שם

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

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

    • partitionKey

      ‫CookiePartitionKey אופציונלי

      ‫Chrome 119 ואילך

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

    • נתיב

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

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

    • sameSite

      ‫SameSiteStatus אופציונלי

      ‫Chrome 51+‎

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

    • מאובטח

      ‫boolean אופציונלי

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

    • storeId

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

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

    • כתובת אתר

      מחרוזת

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

    • ערך

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

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

החזרות

  • ‫Promise<Cookie | undefined>

    ‫Chrome 88 ואילך

אירועים

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