תיאור
אתם יכולים להשתמש ב-API של chrome.cookies
כדי לשלוח שאילתות ולשנות קובצי cookie, וגם כדי לקבל התראות כשהם משתנים.
הרשאות
cookies
מניפסט
כדי להשתמש בממשק ה-API של קובצי cookie, עליך להצהיר על 'קובצי cookie' ב- מניפסט, יחד עם הרשאות מארח עבור כל המארחים שרוצים להשתמש בקובצי ה-Cookie שלהם כדי לגשת אליה. לדוגמה:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
חלוקה למחיצות
קובצי cookie מחולקים למחיצות מאפשרים לאתר לסמן שקובצי cookie מסוימים צריכים להיות מקודדים של המסגרת ברמה העליונה. המשמעות היא שאם אתר א' מוטמע באמצעות iframe באתר ב' והאתר ג', קובץ Cookie עם חלוקה למחיצות יכול להיות בעל ערך שונה בכל אחד מהם.
ב-chrome.cookies
אין תמיכה במחיצות, כלומר כל השיטות קוראות וכותבות קובצי cookie מכל המחיצות. השיטה cookies.set()
שומרת קובצי Cookie ב
מחיצת ברירת המחדל.
פרטים על ההשפעה הכללית של חלוקה למחיצות (partitioning) על תוספים זמינים במאמר אחסון וקובצי cookie.
דוגמאות
אפשר למצוא דוגמה פשוטה לשימוש ב-Cookie API examples/api/cookies. דוגמאות נוספות ועזרה בהצגת קוד המקור זמינות במאמר דוגמאות.
סוגים
Cookie
מייצג מידע על קובץ HTTP cookie.
מאפיינים
-
דומיין
מחרוזת
הדומיין של קובץ ה-cookie (למשל, www.google.com , example.com).
-
expirationDate
מספר אופציונלי
תאריך התפוגה של קובץ ה-cookie כמספר השניות מאז תחילת התקופה של UNIX. לא סופק עבור קובצי cookie של הפעלה.
-
hostOnly
בוליאני
הערך True מוגדר אם קובץ ה-cookie הוא קובץ cookie למארח בלבד (כלומר, המארח של הבקשה חייב להתאים בדיוק לדומיין של קובץ ה-cookie).
-
httpOnly
בוליאני
הערך True אם קובץ ה-cookie מסומן כ-HttpOnly (כלומר, אין גישה לקובץ ה-cookie בסקריפטים בצד הלקוח).
-
שם
מחרוזת
שם קובץ ה-cookie.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome מגרסה 119 ואילךמפתח החלוקה לקריאה או לשינוי של קובצי cookie באמצעות המאפיין 'חלוקה למחיצות'.
-
נתיב
מחרוזת
הנתיב של קובץ ה-cookie.
-
sameSiteגרסה 51 ואילך של Chrome
סטטוס אותו אתר של קובץ ה-cookie (כלומר, אם קובץ ה-cookie נשלח באמצעות בקשות בין אתרים).
-
מאובטח
בוליאני
הערך True מופיע אם קובץ ה-cookie מסומן כמאובטח (כלומר היקף השימוש בו מוגבל לערוצים מאובטחים, בדרך כלל HTTPS).
-
ביקור
בוליאני
הערך הוא True אם קובץ ה-Cookie הוא קובץ Cookie של סשן, בניגוד לקובץ Cookie קבוע עם תאריך תפוגה.
-
storeId
מחרוזת
המזהה של מאגר קובצי ה-cookie שמכיל את קובץ ה-cookie הזה, כפי שצוין ב-getAllCookieStores().
-
ערך
מחרוזת
הערך של קובץ ה-cookie.
CookieDetails
פרטים שיאפשרו לזהות את קובץ ה-cookie.
מאפיינים
-
שם
מחרוזת
שם קובץ ה-cookie שרוצים לגשת אליו.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome 119 ואילךמפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.
-
storeId
מחרוזת אופציונלי
המזהה של מאגר קובצי ה-cookie שבו צריך לחפש את קובץ ה-cookie. כברירת מחדל, ייעשה שימוש במאגר קובצי ה-cookie של הקשר הביצוע הנוכחי.
-
כתובת אתר
מחרוזת
כתובת ה-URL שאליה משויך קובץ ה-Cookie שצריך לגשת אליו. הארגומנט הזה יכול להיות כתובת URL מלאה, ובמקרה כזה המערכת פשוט מתעלמת מכל הנתונים שמופיעים אחרי נתיב כתובת ה-URL (למשל מחרוזת השאילתה). אם הרשאות המארח של כתובת ה-URL הזו לא יצוינו בקובץ המניפסט, הקריאה ל-API תיכשל.
CookiePartitionKey
מייצג מפתח מחיצה של קובץ Cookie עם חלוקה למחיצות.
מאפיינים
-
hasCrossSiteAncestor
boolean אופציונלי
גרסה 130 ואילך של Chromeמציין אם קובץ ה-cookie הוגדר בהקשר חוצה-אתרים. הפעולה הזו מונעת מאתר ברמה עליונה שמוטמע בהקשר של אתרים שונים לגשת לקובצי cookie שהוגדרו על ידי האתר ברמה העליונה בהקשר של אותו אתר.
-
topLevelSite
מחרוזת אופציונלי
האתר ברמה העליונה שבו קובץ ה-Cookie עם החלוקה למחיצות זמין.
CookieStore
מייצג מאגר קובצי cookie בדפדפן. למשל, חלון של מצב פרטי משתמש באחסון נפרד של קובצי cookie מהחלון שאינו פרטי.
מאפיינים
-
id [מזהה]
מחרוזת
המזהה הייחודי של מאגר קובצי ה-cookie.
-
tabIds
number[]
המזהים של כל כרטיסיות הדפדפן שחולקות את מאגר קובצי ה-Cookie הזה.
OnChangedCause
הסיבה לשינוי בקובץ ה-cookie. אם קובץ cookie צורף או הוסר באמצעות קריאה מפורשת ל-chrome.cookies.remove", "גורם" תהיה 'בוטה'. אם קובץ cookie הוסר באופן אוטומטי בגלל תפוגה, הערך של 'cause' יהיה 'expired'. אם קובץ cookie הוסר עקב שהוחלף בתאריך תפוגה שכבר פג, "הסיבה" יוגדר כ-"bullet_overwrite". אם קובץ cookie הוסר באופן אוטומטי בגלל איסוף אשפה, הערך של 'cause' יהיה 'evicted'. אם קובץ cookie הוסר באופן אוטומטי בגלל קריאה מסוג 'set' שהחליפה אותו, הערך של 'cause' יהיה 'overwrite'. תכננו את התגובה בהתאם.
Enum
"expired"
"overwrite"
SameSiteStatus
המצב 'SameSite' של קובץ cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' תואם לקובץ cookie שהוגדר עם 'SameSite=None', 'lax' ל-'SameSite=Lax' ול-'strict' ל-'SameSite=Strict'. 'לא צוין' תואמת לקבוצת קובצי cookie ללא המאפיין SameSite.
Enum
"no_restriction"
"unspecified"
שיטות
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 ואילךיש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
מאחזר את כל קובצי ה-cookie ממאגר קובצי cookie אחד שתואם למידע הנתון. קובצי ה-cookie שיוחזרו ימוינו, והקובץ עם הנתיב הארוך ביותר יופיע ראשון. אם לכמה קובצי Cookie יש אורך נתיב זהה, הראשונים שבהם יש זמן יצירה מוקדם יותר. השיטה הזו מאחזרת קובצי cookie רק לדומיינים שלתוסף יש בהם הרשאות מארח.
פרמטרים
-
פרטים
אובייקט
מידע לסינון קובצי ה-Cookie שמאוחזרים.
-
דומיין
מחרוזת אופציונלי
המדיניות מגבילה את קובצי ה-cookie שאוחזרו רק לקובצי ה-cookie שהדומיינים שלהם תואמים או לתת-דומיינים של הדומיין הזה.
-
שם
מחרוזת אופציונלי
סינון קובצי ה-cookie לפי שם.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome מגרסה 119 ואילךמפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.
-
נתיב
מחרוזת אופציונלי
הגבלת קובצי ה-cookie שאוחזרים רק לאלה שהנתיב שלהם תואם בדיוק למחרוזת הזו.
-
מאובטח
ערך בוליאני אופציונלי
מסנן את קובצי ה-Cookie לפי המאפיין המאובטח שלהם.
-
ביקור
ערך בוליאני אופציונלי
סינון של קובצי cookie זמניים לעומת קובצי cookie קבועים.
-
storeId
מחרוזת אופציונלי
מאגר קובצי ה-Cookie שממנו יש לאחזר את קובצי ה-Cookie. אם השדה הזה לא יצוין, המערכת תשתמש במאגר קובצי ה-cookie של הקשר הביצוע הנוכחי.
-
כתובת אתר
מחרוזת אופציונלי
הגבלת קובצי ה-cookie שאוחזרים רק לאלה שתואמים לכתובת ה-URL שצוינה.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(cookies: Cookie[]) => void
-
קובצי cookie
כל קובצי ה-Cookie הקיימים והתוקפים שתואמים למידע הנתון של קובצי ה-cookie.
-
החזרות
-
התחייבות<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 שהוסרה. אם ההסרה נכשלה מסיבה כלשהי, הערך יהיה 'null' והערך
runtime.lastError
יוגדר.-
שם
מחרוזת
שם קובץ ה-cookie שהוסר.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome מגרסה 119 ואילךמפתח החלוקה לקריאה או לשינוי של קובצי cookie באמצעות המאפיין 'חלוקה למחיצות'.
-
storeId
מחרוזת
המזהה של מאגר קובצי ה-Cookie שממנו קובץ ה-Cookie הוסר.
-
כתובת אתר
מחרוזת
כתובת ה-URL המשויכת לקובץ ה-cookie שהוסר.
-
-
החזרות
-
Promise<object | לא מוגדר>
Chrome מגרסה 88 ואילךהבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
set()
chrome.cookies.set(
details: object,
callback?: function,
)
מגדירה קובץ cookie עם הנתונים הנתונים של קובץ ה-cookie; עשויים להחליף קובצי cookie מקבילים, אם יש כאלה.
פרמטרים
-
פרטים
אובייקט
פרטים על קובץ ה-cookie שמוגדר.
-
דומיין
מחרוזת אופציונלי
הדומיין של קובץ ה-cookie. אם לא מציינים את זה, קובץ ה-cookie הופך לקובץ cookie של מארח בלבד.
-
expirationDate
מספר אופציונלי
תאריך התפוגה של קובץ ה-cookie כמספר השניות מאז ראשית זמן יוניקס. אם לא יוזנו, קובץ ה-cookie יהפוך לקובץ cookie של סשן.
-
httpOnly
בוליאני אופציונלי
האם קובץ ה-cookie צריך להיות מסומן כ-HttpOnly. ברירת המחדל היא False.
-
שם
מחרוזת אופציונלי
השם של קובץ ה-cookie. אם לא יוזנו, המערכת תרוקן כברירת מחדל.
-
partitionKey
CookiePartitionKey אופציונלי
Chrome 119 ואילךמפתח המחיצה לקריאה או לשינוי של קובצי Cookie עם המאפיין Partitioned.
-
נתיב
מחרוזת אופציונלי
הנתיב של קובץ ה-cookie. ברירת המחדל היא החלק של הנתיב בפרמטר של כתובת ה-URL.
-
sameSite
SameSiteStatus אופציונלי
Chrome 51 ואילךסטטוס ה-SameSite של קובץ ה-cookie. ברירת המחדל היא "unspecified". כלומר, אם לא צוין, קובץ ה-cookie מוגדר ללא ציון מאפיין SameSite.
-
מאובטח
ערך בוליאני אופציונלי
האם קובץ ה-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 | לא מוגדר>
Chrome מגרסה 88 ואילךהבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
אירועים
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
מופעל כשקובץ cookie מוגדר או מוסר. במקרה מיוחד, חשוב לשים לב שעדכון המאפיינים של קובץ cookie מיושם בתהליך דו-שלבי: תחילה מתבצעת הסרה מלאה של קובץ ה-cookie המיועד לעדכון, ולאחר מכן נוצרת התראה עם הכיתוב "סיבה" של 'overwrite' הקצר הזה. התשובות שלך יעזרו לנו להשתפר. לאחר מכן, קובץ cookie חדש נכתב עם הערכים המעודכנים, ותיצור התראה שנייה עם המילה 'סיבה' 'בוטה'.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(changeInfo: object) => void
-
changeInfo
אובייקט
-
גורם
הסיבה הבסיסית לשינוי של קובץ ה-cookie.
-
קובץ cookie
מידע על קובץ ה-cookie שהוגדר או הוסר.
-
הוסר
בוליאני
הערך True מופיע אם קובץ cookie הוסר.
-
-