chrome.cookies

תיאור

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

הרשאות

cookies

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

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

חלוקה למחיצות (partitioning)

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

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

לפרטים על ההשפעה הכללית של חלוקה למחיצות (partitioning) עבור תוספים, אפשר לעיין במאמר אחסון וקובצי Cookie

דוגמאות

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

סוגים

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

מאפיינים

  • דומיין

    מחרוזת

    הדומיין של קובץ ה-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

    Chrome 51 ואילך

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

  • מאובטח

    בוליאני

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

  • ביקור

    בוליאני

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

  • storeId

    מחרוזת

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

  • ערך

    מחרוזת

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

CookieDetails

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

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

מאפיינים

  • שם

    מחרוזת

    שם קובץ ה-cookie שרוצים לגשת אליו.

  • partitionKey

    CookiePartitionKey אופציונלי

    Chrome 119 ואילך

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

  • storeId

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

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

  • כתובת אתר

    מחרוזת

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

CookiePartitionKey

Chrome 119 ואילך

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

מאפיינים

  • hasCrossSiteAncestor

    ערך בוליאני אופציונלי

    בהמתנה

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

  • topLevelSite

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

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

CookieStore

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

מאפיינים

  • id [מזהה]

    מחרוזת

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

  • tabIds

    מספר[]

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

OnChangedCause

Chrome 44 ואילך

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

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

Enum

שיטות

get()

Promise 
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 | לא מוגדר>

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

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

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • שם

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

      מסנן את קובצי ה-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()

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

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

פרמטרים

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

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

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

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

החזרות

  • Promise<CookieStore[]>

    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()

Promise 
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

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

    • דומיין

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

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

    • expirationDate

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

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

    • httpOnly

      ערך בוליאני אופציונלי

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

    • שם

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

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

    • partitionKey

      CookiePartitionKey אופציונלי

      Chrome 119 ואילך

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

    • נתיב

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

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

    • sameSite

      SameSiteStatus אופציונלי

      Chrome 51 ואילך

      הסטטוס של קובץ ה-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 הוסר.