chrome.cookies

תיאור

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

הרשאות

cookies

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

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

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

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

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

במאמר אחסון וקובצי cookie אפשר לקרוא מידע נוסף על ההשפעה הכללית של חלוקה למחיצות (partitioning) בתוספים.

דוגמאות

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

סוגים

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

תכונות

  • דומיין

    מחרוזת

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

  • expirationDate

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

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

  • hostOnly

    boolean

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

  • httpOnly

    boolean

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

  • name

    מחרוזת

    שם קובץ ה-Cookie.

  • partitionKey

    CookiePartitionKey אופציונלי

    Chrome 119 ומעלה

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

  • נתיב

    מחרוזת

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

  • sameSite

    SameSiteStatus

    Chrome 51 ומעלה

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

  • מאובטח

    boolean

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

  • סשן

    boolean

    הערך הוא True אם קובץ ה-cookie הוא קובץ cookie של סשן, לעומת קובץ cookie קבוע עם תאריך תפוגה.

  • storeId

    מחרוזת

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

  • value

    מחרוזת

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

CookieDetails

Chrome 88 ומעלה

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

תכונות

  • name

    מחרוזת

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

  • partitionKey

    CookiePartitionKey אופציונלי

    Chrome 119 ומעלה

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

  • storeId

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

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

  • כתובת אתר

    מחרוזת

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

CookiePartitionKey

Chrome 119 ומעלה

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

תכונות

  • topLevelSite

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

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

CookieStore

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

תכונות

  • id

    מחרוזת

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

  • tabIds

    מספר[]

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

OnChangedCause

Chrome 44 ואילך

הסיבה לשינוי בקובץ ה-cookie. אם קובץ cookie נוסף או הוסר על ידי קריאה מפורשת ל-'chrome.cookies.remove', 'הסיבה' תיספר כ-'explicit'. אם קובץ cookie הוסר באופן אוטומטי עקב תפוגה, המשמעות של 'הסיבה' תהיה 'התוקף פג'. אם קובץ cookie הוסר כי הוא הוחלף בתאריך תפוגה שכבר פג, הערך של 'הסיבה' יוגדר כ-' חשיפה_overwrite'. אם קובץ cookie הוסר באופן אוטומטי בגלל איסוף אשפה, 'הסיבה' תוסר. אם קובץ cookie הוסר באופן אוטומטי עקב קריאה ל-set (set) שהחלפתו את קובץ ה-cookie, המשמעות של 'סיבת' היא 'החלפה'. כדאי לתכנן את התגובה בהתאם.

טיפוסים בני מנייה (enum)

SameSiteStatus

Chrome 51 ומעלה

מצב 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"

שיטות

get()

הבטחה 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    CookieDetails

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

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

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

    (cookie?: Cookie)=>void

    • קובץ Cookie

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

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

החזרות

  • הבטחה<קובץ cookie|לא מוגדר>

    Chrome 88 ומעלה

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

getAll()

הבטחה 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • name

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

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

    • partitionKey

      CookiePartitionKey אופציונלי

      Chrome 119 ומעלה

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

    • נתיב

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

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

    • מאובטח

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

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

    • סשן

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

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

    • storeId

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

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

    • כתובת אתר

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

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

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

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

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

    (cookies: Cookie[])=>void

    • קובצי cookie

      קובץ Cookie[]

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

החזרות

  • Promise<Cookie[]>

    Chrome 88 ומעלה

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

getAllCookieStores()

הבטחה 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

פרמטרים

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

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

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

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

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

החזרות

  • Promise<CookieStore[]>

    Chrome 88 ומעלה

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

remove()

הבטחה 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    CookieDetails

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

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

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

    (details?: object)=>void

    • פרטים

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

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

      • name

        מחרוזת

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

      • partitionKey

        CookiePartitionKey אופציונלי

        Chrome 119 ומעלה

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

      • storeId

        מחרוזת

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

      • כתובת אתר

        מחרוזת

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

החזרות

  • Promise<object|undefined>

    Chrome 88 ומעלה

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

set()

הבטחה 
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • expirationDate

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

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

    • httpOnly

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

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

    • name

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

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

    • partitionKey

      CookiePartitionKey אופציונלי

      Chrome 119 ומעלה

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

    • נתיב

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

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

    • sameSite

      SameSiteStatus אופציונלי

      Chrome 51 ומעלה

      סטטוס קובץ ה-cookie באותו אתר. ברירת המחדל היא "un specified" (לא צוין). כלומר, אם לא צוין קובץ cookie, קובץ ה-cookie מוגדר בלי לציין מאפיין SameSite.

    • מאובטח

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

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

    • storeId

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

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

    • כתובת אתר

      מחרוזת

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

    • value

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

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

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

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

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

    (cookie?: Cookie)=>void

    • קובץ Cookie

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

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

החזרות

  • הבטחה<קובץ cookie|לא מוגדר>

    Chrome 88 ומעלה

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

אירועים

onChanged

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

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

פרמטרים

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

    פונקציה

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

    (changeInfo: object)=>void

    • changeInfo

      אובייקט

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

      • קובץ Cookie

        קובץ Cookie

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

      • הוסר

        boolean

        True אם הוסר קובץ cookie.