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. דוגמאות נוספות ועזרה בהצגת קוד המקור זמינות במאמר דוגמאות.

סוגים

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

מאפיינים

  • מחרוזת

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

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

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

  • בוליאני

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

  • בוליאני

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

  • מחרוזת

    שם קובץ ה-cookie.

  • CookiePartitionKey אופציונלי

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

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

  • מחרוזת

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

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

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

  • בוליאני

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

  • בוליאני

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

  • מחרוזת

    המזהה של מאגר קובצי ה-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 עם זמן היצירה המוקדם ביותר.

פרמטרים

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

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

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

    (cookie?: Cookie) => void

    • קובץ 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()

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

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

פרמטרים

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

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

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

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

החזרות

  • Promise&lt;CookieStore[]&gt;

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

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

remove()

Promise
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 שהוגדר. אם ההגדרה תיכשל מסיבה כלשהי, הערך יהיה '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 שהוגדר או הוסר.

      • הוסר

        בוליאני

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