chrome.cookies

תיאור

אתם יכולים להשתמש ב-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

  SameSiteStatus

  גרסה 51 ואילך של Chrome

  סטטוס אותו אתר של קובץ ה-cookie (כלומר, אם קובץ ה-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 אופציונלי

  גרסה 130 ואילך של Chrome

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

• topLevelSite

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

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

CookieStore

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

מאפיינים

• id [מזהה]

  מחרוזת

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

• tabIds

  number[]

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

OnChangedCause

Chrome 44 ואילך

הסיבה לשינוי בקובץ ה-cookie. אם קובץ cookie צורף או הוסר באמצעות קריאה מפורשת ל-chrome.cookies.remove", "גורם" תהיה 'בוטה'. אם קובץ cookie הוסר באופן אוטומטי בגלל תפוגה, הערך של 'cause' יהיה 'expired'. אם קובץ cookie הוסר עקב שהוחלף בתאריך תפוגה שכבר פג, "הסיבה" יוגדר כ-"bullet_overwrite". אם קובץ cookie הוסר באופן אוטומטי בגלל איסוף אשפה, הערך של 'cause' יהיה 'evicted'. אם קובץ cookie הוסר באופן אוטומטי בגלל קריאה מסוג 'set' שהחליפה אותו, הערך של 'cause' יהיה 'overwrite'. תכננו את התגובה בהתאם.

Enum

"expired"

"overwrite"

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'. 'לא צוין' תואמת לקבוצת קובצי cookie ללא המאפיין SameSite.

Enum

"no_restriction"

"unspecified"

שיטות

get()

הבטחה

chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

פרמטרים

• פרטים

  CookieDetails

• קריאה חוזרת (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.

החזרות

• התחייבות<Cookie[]>

  Chrome מגרסה 88 ואילך

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

getAllCookieStores()

Promise

chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

פרמטרים

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

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

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

  (cookieStores: CookieStore[]) => void

  • cookieStores

    CookieStore[]

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

החזרות

• Promise&lt;CookieStore[]&gt;

  Chrome מגרסה 88 ואילך

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

remove()

Promise

chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

פרמטרים

• פרטים

  CookieDetails

• קריאה חוזרת (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

    אובייקט

    • גורם

      OnChangedCause

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

    • קובץ cookie

      קובץ Cookie

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

    • הוסר

      בוליאני

      הערך True מופיע אם קובץ cookie הוסר.