chrome.cookies

תיאור

אפשר להשתמש ב-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.

דוגמאות

דוגמה פשוטה לשימוש ב-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()

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): 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 שצוינה.

  • callback

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

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

    (cookies: Cookie[]) => void

    • קובצי cookie

      Cookie[]

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

החזרות

  • Promise<Cookie[]>

    ‫Chrome 88 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

getAllCookieStores()

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

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

פרמטרים

  • callback

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

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

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

החזרות

  • Promise<CookieStore[]>

    ‫Chrome 88 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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>

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

remove()

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

מחיקת קובץ 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>

    ‫Chrome 88 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

set()

Promise 
chrome.cookies.set(
  details: object,
  callback?: function,
): 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. אם לא מציינים ערך, ברירת המחדל היא ריק.

  • callback

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

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

    (cookie?: Cookie) => void

    • קובץ Cookie

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

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

החזרות

  • ‫Promise<Cookie | undefined>

    ‫Chrome 88 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

אירועים

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