תיאור
אפשר להשתמש ב-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
מייצג מידע על קובץ cookie מסוג HTTP.
תכונות
-
דומיין
string
הדומיין של קובץ ה-cookie (למשל, "www.google.com", "example.com").
-
expirationDate
מספר אופציונלי
תאריך התפוגה של קובץ ה-cookie כמספר השניות מאז תקופת UNIX לא סופק לקובצי cookie של הפעלה.
-
hostOnly
boolean
הערך הוא True אם קובץ ה-cookie הוא קובץ cookie של מארח בלבד (כלומר, מארח הבקשה חייב להתאים בדיוק לדומיין של קובץ ה-cookie).
-
httpOnly
boolean
True אם קובץ ה-cookie מסומן כ-HttpOnly (כלומר, קובץ ה-cookie לא נגיש לסקריפטים בצד הלקוח).
-
name
string
שם קובץ ה-Cookie.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome 119 ומעלהמפתח החלוקה לקריאה או לשינוי של קובצי cookie עם המאפיין 'חלוקה למחיצות'.
-
נתיב
string
הנתיב של קובץ ה-cookie.
-
sameSiteChrome 51 ומעלה
הסטטוס של קובץ ה-cookie באותו אתר (כלומר, אם קובץ ה-cookie נשלח עם בקשות בין אתרים).
-
מאובטח
boolean
True אם קובץ ה-cookie מסומן כמאובטח (כלומר, ההיקף שלו מוגבל לערוצים מאובטחים, בדרך כלל HTTPS).
-
סשן
boolean
הערך הוא True אם קובץ ה-cookie הוא קובץ cookie של סשן, לעומת קובץ cookie קבוע עם תאריך תפוגה.
-
storeId
string
המזהה של מאגר קובצי ה-cookie שמכיל את קובץ ה-cookie הזה, כפי שהוא מופיע ב-getAllCookieStores().
-
value
string
הערך של קובץ ה-cookie.
CookieDetails
פרטים לזיהוי קובץ ה-cookie.
תכונות
-
name
string
שם קובץ ה-Cookie שאליו יש לגשת.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome 119 ומעלהמפתח החלוקה לקריאה או לשינוי של קובצי cookie עם המאפיין 'חלוקה למחיצות'.
-
storeId
מחרוזת אופציונלי
המזהה של מאגר קובצי ה-cookie שבו יש לחפש את קובץ ה-cookie. כברירת מחדל, ייעשה שימוש במאגר קובצי ה-cookie של ההקשר הביצוע הנוכחי.
-
כתובת אתר
string
כתובת ה-URL שאליה משויך קובץ ה-cookie שאליו צריך לגשת. הארגומנט הזה יכול להיות כתובת URL מלאה. במקרה כזה, המערכת מתעלמת מכל הנתונים שמופיעים אחרי נתיב כתובת ה-URL (למשל, מחרוזת השאילתה). אם הרשאות המארח לכתובת ה-URL הזו לא מפורטות בקובץ המניפסט, הקריאה ל-API תיכשל.
CookiePartitionKey
מייצג מפתח חלוקה של קובץ cookie עם חלוקה למחיצות.
תכונות
-
topLevelSite
מחרוזת אופציונלי
האתר ברמה העליונה שבו זמין קובץ ה-cookie עם החלוקה למחיצות.
CookieStore
מייצג מאגר קובצי cookie בדפדפן. למשל, בחלון של מצב פרטי נעשה שימוש במאגר קובצי cookie נפרד מחלון שאינו של גלישה בסתר.
תכונות
-
id
string
המזהה הייחודי של מאגר קובצי ה-cookie.
-
tabIds
מספר[]
המזהים של כל הכרטיסיות בדפדפן שחולקות מאגר קובצי cookie זה.
OnChangedCause
הסיבה לשינוי בקובץ ה-cookie. אם קובץ cookie נוסף או הוסר על ידי קריאה מפורשת ל-'chrome.cookies.remove', 'הסיבה' תיספר כ-'explicit'. אם קובץ cookie הוסר באופן אוטומטי עקב תפוגה, המשמעות של 'הסיבה' תהיה 'התוקף פג'. אם קובץ cookie הוסר כי הוא הוחלף בתאריך תפוגה שכבר פג, הערך של 'הסיבה' יוגדר כ-' חשיפה_overwrite'. אם קובץ cookie הוסר באופן אוטומטי בגלל איסוף אשפה, 'הסיבה' תוסר. אם קובץ cookie הוסר באופן אוטומטי עקב קריאה ל-set (set) שהחלפתו את קובץ ה-cookie, המשמעות של 'סיבת' היא 'החלפה'. כדאי לתכנן את התגובה בהתאם.
טיפוסים בני מנייה (enum)
SameSiteStatus
מצב 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 עם מועד היצירה המוקדם ביותר.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(cookie?: Cookie) => void
-
קובץ Cookie
קובץ cookie אופציונלי
מכילה פרטים על קובץ ה-Cookie. הפרמטר הזה הוא null אם לא נמצא קובץ cookie כזה.
-
החזרות
-
Promise<Cookie | undefined>
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.
-
החזרות
-
Promise<Cookie[]>
Chrome 88 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
רשימה של כל מאגרי קובצי ה-cookie הקיימים.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(cookieStores: CookieStore[]) => void
-
cookieStores
כל מאגרי קובצי ה-cookie הקיימים.
-
החזרות
-
Promise<CookieStore[]>
Chrome 88 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
מחיקת קובץ cookie לפי שם.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(details?: object) => void
-
פרטים
אובייקט אופציונלי
מכילה פרטים על קובץ ה-cookie שהוסר. אם ההסרה נכשלה מסיבה כלשהי, הערך בשדה
runtime.lastError
יוגדר כ-null.-
name
string
שם קובץ ה-Cookie שהוסר.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome 119 ומעלהמפתח החלוקה לקריאה או לשינוי של קובצי cookie עם המאפיין 'חלוקה למחיצות'.
-
storeId
string
המזהה של מאגר קובצי ה-Cookie שממנו הוסר קובץ ה-Cookie.
-
כתובת אתר
string
כתובת ה-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 של הקשר הביצוע הנוכחי.
-
כתובת אתר
string
ה-URI של הבקשה שיש לשייך להגדרה של קובץ ה-Cookie. הערך הזה יכול להשפיע על ערכי ברירת המחדל של הדומיין והנתיב של קובץ ה-cookie שנוצר. אם הרשאות המארח לכתובת ה-URL הזו לא מפורטות בקובץ המניפסט, הקריאה ל-API תיכשל.
-
value
מחרוזת אופציונלי
הערך של קובץ ה-cookie. אם השדה לא צוין, הוא ריק כברירת מחדל.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(cookie?: Cookie) => void
-
קובץ Cookie
קובץ cookie אופציונלי
מכילה פרטים על קובץ ה-cookie שהוגדר. אם ההגדרה נכשלה מסיבה כלשהי, הערך בשדה
runtime.lastError
יוגדר כ-null.
-
החזרות
-
Promise<Cookie | undefined>
Chrome 88 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
מופעל כאשר קובץ cookie מוגדר או כשמסירים אותו. במקרה מיוחד, חשוב לזכור שעדכון המאפיינים של קובץ cookie מיושם כתהליך דו-שלבי: קובץ ה-cookie שיש לעדכן מוסר לחלוטין, ויוצר התראה עם "סיבת" החלפה. לאחר מכן, קובץ cookie חדש נכתב עם הערכים המעודכנים, ונוצר התראה שנייה עם "cause" "explicit".
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(changeInfo: object) => void
-
changeInfo
אובייקט
-
cause
הסיבה לשינוי בקובץ ה-cookie.
-
קובץ Cookie
מידע על קובץ ה-cookie שהוגדר או הוסר.
-
הוסר
boolean
True אם הוסר קובץ cookie.
-
-