chrome.cookies

توضیحات

از API chrome.cookies برای جستجو و تغییر کوکی‌ها و مطلع شدن از تغییرات آنها استفاده کنید.

مجوزها

cookies

مانیفست

برای استفاده از API کوکی‌ها، باید مجوز "کوکی‌ها" را در مانیفست خود، به همراه مجوزهای میزبان برای هر میزبان که می‌خواهید به کوکی‌های آن دسترسی داشته باشید، اعلام کنید. برای مثال:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}
پارتیشن بندی

کوکی‌های پارتیشن‌بندی شده به یک سایت اجازه می‌دهند تا مشخص کند که کوکی‌های خاص باید با مبدأ فریم سطح بالا مطابقت داشته باشند. این بدان معناست که اگر سایت A با استفاده از یک iframe در سایت B و سایت C جاسازی شده باشد، یک کوکی پارتیشن‌بندی شده می‌تواند در هر کدام مقدار متفاوتی داشته باشد.

chrome.cookies از پارتیشن‌بندی پشتیبانی نمی‌کند، به این معنی که همه متدها کوکی‌ها را از همه پارتیشن‌ها می‌خوانند و می‌نویسند. متد cookies.set() کوکی‌ها را در پارتیشن پیش‌فرض ذخیره می‌کند.

برای جزئیات بیشتر در مورد تأثیر کلی پارتیشن‌بندی برای افزونه‌ها، به بخش «فضای ذخیره‌سازی و کوکی‌ها» مراجعه کنید.

مثال‌ها

می‌توانید یک مثال ساده از استفاده از API کوکی‌ها را در دایرکتوری examples/api/cookies پیدا کنید. برای مثال‌های دیگر و کمک در مشاهده کد منبع، به Samples مراجعه کنید.

انواع
Cookie

اطلاعات مربوط به یک کوکی HTTP را نشان می‌دهد.

خواص
  • دامنه

    رشته

    دامنه کوکی (مثلاً "www.google.com" ، "example.com").

  • تاریخ انقضا

    شماره اختیاری

    تاریخ انقضای کوکی به صورت تعداد ثانیه‌ها از زمان آغاز یونیکس. برای کوکی‌های جلسه‌ای ارائه نشده است.

  • فقط میزبان

    بولی

    اگر کوکی فقط برای میزبان باشد (یعنی میزبان درخواست باید دقیقاً با دامنه کوکی مطابقت داشته باشد)، صحیح است.

  • فقط http

    بولی

    اگر کوکی به صورت HttpOnly علامت‌گذاری شده باشد (یعنی کوکی برای اسکریپت‌های سمت کلاینت غیرقابل دسترسی باشد)، صحیح است.

  • نام

    رشته

    نام کوکی.

  • کلید پارتیشن

    کلید کوکی ( اختیاری)

    کروم ۱۱۹+

    کلید پارتیشن برای خواندن یا تغییر کوکی‌ها با ویژگی پارتیشن‌بندی شده.

  • مسیر

    رشته

    مسیر کوکی.

  • کروم ۵۱+

    وضعیت هم-سایتی کوکی (یعنی اینکه آیا کوکی با درخواست‌های بین-سایتی ارسال می‌شود یا خیر).

  • امن

    بولی

    اگر کوکی به عنوان Secure علامت‌گذاری شده باشد (یعنی دامنه آن محدود به کانال‌های امن، معمولاً HTTPS، باشد)، صحیح است.

  • جلسه

    بولی

    اگر کوکی از نوع کوکی جلسه‌ای باشد، در مقایسه با یک کوکی ماندگار با تاریخ انقضا، صحیح است.

  • شناسه فروشگاه

    رشته

    شناسه‌ی محل ذخیره‌سازی کوکی حاوی این کوکی، همانطور که در تابع getAllCookieStores() ارائه شده است.

  • ارزش

    رشته

    ارزش کوکی.

CookieDetails
کروم ۸۸+

جزئیاتی برای شناسایی کوکی.

خواص
  • نام

    رشته

    نام کوکی که قرار است به آن دسترسی پیدا کنید.

  • کلید پارتیشن

    کلید کوکی ( اختیاری)

    کروم ۱۱۹+

    کلید پارتیشن برای خواندن یا تغییر کوکی‌ها با ویژگی پارتیشن‌بندی شده.

  • شناسه فروشگاه

    رشته اختیاری

    شناسه‌ی محل ذخیره‌سازی کوکی که کوکی در آن جستجو می‌شود. به طور پیش‌فرض، محل ذخیره‌سازی کوکیِ زمینه‌ی اجرایی فعلی استفاده خواهد شد.

  • آدرس اینترنتی

    رشته

    URL ای که کوکی برای دسترسی به آن مرتبط است. این آرگومان ممکن است یک URL کامل باشد، که در این صورت هر داده‌ای که پس از مسیر URL قرار می‌گیرد (مثلاً رشته پرس و جو) به سادگی نادیده گرفته می‌شود. اگر مجوزهای میزبان برای این URL در فایل مانیفست مشخص نشده باشد، فراخوانی API با شکست مواجه خواهد شد.

CookiePartitionKey
کروم ۱۱۹+

کلید پارتیشن یک کوکی پارتیشن‌بندی شده را نشان می‌دهد.

خواص
  • hasCrossSiteAncestor

    بولی اختیاری

    کروم ۱۳۰+

    نشان می‌دهد که آیا کوکی در یک زمینه سایت متقاطع تنظیم شده است یا خیر. این مانع از دسترسی یک سایت سطح بالا که در یک زمینه سایت متقاطع تعبیه شده است به کوکی‌های تنظیم شده توسط سایت سطح بالا در یک زمینه سایت مشابه می‌شود.

  • سایت سطح بالا

    رشته اختیاری

    بالاترین سطح سایتی که کوکی پارتیشن‌بندی شده در آن موجود است.

CookieStore

نشان‌دهنده‌ی محل ذخیره‌سازی کوکی‌ها در مرورگر است. برای مثال، یک پنجره‌ی حالت ناشناس از محل ذخیره‌سازی کوکی‌های جداگانه‌ای نسبت به یک پنجره‌ی غیر ناشناس استفاده می‌کند.

خواص
  • شناسه

    رشته

    شناسه منحصر به فرد برای فروشگاه کوکی.

  • شناسه‌های برگه

    شماره[]

    شناسه‌های تمام تب‌های مرورگر که این فروشگاه کوکی را به اشتراک می‌گذارند.

FrameDetails
کروم ۱۳۲+

جزئیات برای شناسایی قاب.

خواص
  • شناسه سند

    رشته اختیاری

    شناسه منحصر به فرد برای سند. اگر frameId و/یا tabId ارائه شوند، اعتبارسنجی می‌شوند تا با سندی که توسط شناسه سند ارائه شده یافت می‌شود، مطابقت داشته باشند.

  • شناسه قاب

    شماره اختیاری

    شناسه منحصر به فرد برای قاب درون برگه.

  • شناسه برگه

    شماره اختیاری

    شناسه منحصر به فرد برای برگه‌ای که قاب در آن قرار دارد.

OnChangedCause
کروم ۴۴+

دلیل اصلی تغییر کوکی. اگر کوکی‌ای از طریق فراخوانی صریح "chrome.cookies.remove" درج یا حذف شده باشد، "cause" "explicit" خواهد بود. اگر کوکی‌ای به دلیل انقضا به طور خودکار حذف شده باشد، "cause" "expired" خواهد بود. اگر کوکی‌ای به دلیل رونویسی با تاریخ انقضایی که قبلاً منقضی شده است حذف شده باشد، "cause" روی "expired_overwrite" تنظیم می‌شود. اگر کوکی‌ای به دلیل جمع‌آوری زباله به طور خودکار حذف شده باشد، "cause" "evicted" خواهد شد. اگر کوکی‌ای به دلیل فراخوانی "set" که آن را رونویسی کرده است به طور خودکار حذف شده باشد، "cause" "overwrite" خواهد بود. پاسخ خود را بر این اساس برنامه‌ریزی کنید.

شمارشی

"اخراج شده"

«منقضی شده»

«صریح»

"بازنویسی_منقضی شده"

"رونویسی"

SameSiteStatus
کروم ۵۱+

وضعیت «SameSite» یک کوکی (https://tools.ietf.org/html/draft-west-first-party-cookies). «no_restriction» مربوط به مجموعه‌ای از کوکی‌ها با «SameSite=None»، «lax» مربوط به «SameSite=Lax» و «strict» مربوط به «SameSite=Strict» است. «unspecified» مربوط به مجموعه‌ای از کوکی‌ها بدون ویژگی SameSite است.

شمارشی

"بدون_محدودیت"

"سهل‌انگار"

"سختگیرانه"

«نامشخص»

روش‌ها
get()
وعده
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

اطلاعات مربوط به یک کوکی را بازیابی می‌کند. اگر بیش از یک کوکی با نام مشابه برای URL داده شده وجود داشته باشد، کوکی با طولانی‌ترین مسیر بازگردانده می‌شود. برای کوکی‌هایی با طول مسیر یکسان، کوکی با اولین زمان ایجاد بازگردانده می‌شود.

پارامترها
  • جزئیات

    جزئیات کوکی

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (cookie?: Cookie) => void

    • کوکی

      کوکی اختیاری

      شامل جزئیاتی در مورد کوکی است. اگر چنین کوکی‌ای یافت نشود، این پارامتر تهی است.

بازگشت‌ها

  • قول < کوکی | تعریف نشده>

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getAll()
وعده
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

تمام کوکی‌های یک فروشگاه کوکی که با اطلاعات داده شده مطابقت دارند را بازیابی می‌کند. کوکی‌های برگردانده شده مرتب می‌شوند و کوکی‌هایی که طولانی‌ترین مسیر را دارند، در ابتدا قرار می‌گیرند. اگر چندین کوکی طول مسیر یکسانی داشته باشند، آن‌هایی که اولین زمان ایجاد را دارند، در ابتدا قرار می‌گیرند. این روش فقط کوکی‌های دامنه‌هایی را بازیابی می‌کند که افزونه به آن‌ها مجوز میزبانی دارد.

پارامترها
  • جزئیات

    شیء

    اطلاعاتی برای فیلتر کردن کوکی‌های بازیابی شده.

    • دامنه

      رشته اختیاری

      کوکی‌های بازیابی‌شده را به آن‌هایی محدود می‌کند که دامنه‌هایشان با این کوکی مطابقت دارد یا زیردامنه‌های آن هستند.

    • نام

      رشته اختیاری

      کوکی‌ها را بر اساس نام فیلتر می‌کند.

    • کلید پارتیشن

      کلید کوکی ( اختیاری)

      کروم ۱۱۹+

      کلید پارتیشن برای خواندن یا تغییر کوکی‌ها با ویژگی پارتیشن‌بندی شده.

    • مسیر

      رشته اختیاری

      کوکی‌های بازیابی شده را به آنهایی محدود می‌کند که مسیر آنها دقیقاً با این رشته مطابقت دارد.

    • امن

      بولی اختیاری

      کوکی‌ها را بر اساس ویژگی Secure آنها فیلتر می‌کند.

    • جلسه

      بولی اختیاری

      کوکی‌های جلسه‌ای را در مقابل کوکی‌های دائمی فیلتر می‌کند.

    • شناسه فروشگاه

      رشته اختیاری

      محل ذخیره کوکی‌ها برای بازیابی کوکی‌ها. در صورت حذف، محل ذخیره کوکی‌های زمینه اجرایی فعلی استفاده خواهد شد.

    • آدرس اینترنتی

      رشته اختیاری

      کوکی‌های بازیابی شده را به آنهایی که با URL داده شده مطابقت دارند، محدود می‌کند.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (cookies: Cookie[]) => void

    • کوکی‌ها

      کوکی []

      تمام کوکی‌های موجود و منقضی نشده که با اطلاعات کوکی داده شده مطابقت دارند.

بازگشت‌ها

  • قول< کوکی []>

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getAllCookieStores()
وعده
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

تمام فروشگاه‌های کوکی موجود را فهرست می‌کند.

پارامترها
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (cookieStores: CookieStore[]) => void

    • فروشگاه‌های کوکی

      فروشگاه کوکی []

      تمام فروشگاه‌های کلوچه موجود.

بازگشت‌ها
  • کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getPartitionKey()
قول کروم ۱۳۲+
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

کلید پارتیشن برای فریم مشخص شده.

پارامترها
  • جزئیات

    جزئیات قاب

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (details: object) => void

    • جزئیات

      شیء

      شامل جزئیاتی در مورد کلید پارتیشن بازیابی شده است.

      • کلید پارتیشن

        کلید پارتیشن کوکی

        کلید پارتیشن برای خواندن یا تغییر کوکی‌ها با ویژگی پارتیشن‌بندی شده.

بازگشت‌ها

  • قول دادن<object>

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

remove()
وعده
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

یک کوکی را بر اساس نام حذف می‌کند.

پارامترها
  • جزئیات

    جزئیات کوکی

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (details?: object) => void

    • جزئیات

      شیء اختیاری

      شامل جزئیاتی درباره کوکی حذف شده است. اگر حذف به هر دلیلی ناموفق باشد، promise رد خواهد شد.

      • نام

        رشته

        نام کوکی حذف شده.

      • کلید پارتیشن

        کلید کوکی ( اختیاری)

        کروم ۱۱۹+

        کلید پارتیشن برای خواندن یا تغییر کوکی‌ها با ویژگی پارتیشن‌بندی شده.

      • شناسه فروشگاه

        رشته

        شناسه‌ی محل ذخیره‌سازی کوکی که کوکی از آن حذف شده است.

      • آدرس اینترنتی

        رشته

        نشانی اینترنتی (URL) مرتبط با کوکی حذف شده.

بازگشت‌ها

  • قول <object | undefined>

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

set()
وعده
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

یک کوکی با داده‌های کوکی داده شده تنظیم می‌کند؛ در صورت وجود، ممکن است کوکی‌های معادل را بازنویسی کند.

پارامترها
  • جزئیات

    شیء

    جزئیات مربوط به کوکی تنظیم شده.

    • دامنه

      رشته اختیاری

      دامنه کوکی. در صورت حذف، کوکی به یک کوکی فقط میزبان تبدیل می‌شود.

    • تاریخ انقضا

      شماره اختیاری

      تاریخ انقضای کوکی به صورت تعداد ثانیه‌ها از زمان آغاز یونیکس. در صورت حذف، کوکی به یک کوکی جلسه‌ای تبدیل می‌شود.

    • فقط http

      بولی اختیاری

      اینکه آیا کوکی باید به عنوان HttpOnly علامت‌گذاری شود یا خیر. مقدار پیش‌فرض false است.

    • نام

      رشته اختیاری

      نام کوکی. در صورت حذف، به طور پیش‌فرض خالی است.

    • کلید پارتیشن

      کلید کوکی ( اختیاری)

      کروم ۱۱۹+

      کلید پارتیشن برای خواندن یا تغییر کوکی‌ها با ویژگی پارتیشن‌بندی شده.

    • مسیر

      رشته اختیاری

      مسیر کوکی. به طور پیش‌فرض بخش مسیر پارامتر url است.

    • همان سایت

      SameSiteStatus اختیاری

      کروم ۵۱+

      وضعیت همان سایت کوکی. به طور پیش‌فرض روی "نامشخص" است، یعنی اگر حذف شود، کوکی بدون مشخص کردن ویژگی SameSite تنظیم می‌شود.

    • امن

      بولی اختیاری

      اینکه آیا کوکی باید به عنوان امن علامت‌گذاری شود یا خیر. مقدار پیش‌فرض false است.

    • شناسه فروشگاه

      رشته اختیاری

      شناسه‌ی محل ذخیره‌سازی کوکی که کوکی در آن تنظیم می‌شود. به طور پیش‌فرض، کوکی در محل ذخیره‌سازی کوکیِ زمینه‌ی اجرایی فعلی تنظیم می‌شود.

    • آدرس اینترنتی

      رشته

      آدرس اینترنتی درخواست (URI) برای مرتبط کردن با تنظیمات کوکی. این مقدار می‌تواند بر مقادیر پیش‌فرض دامنه و مسیر کوکی ایجاد شده تأثیر بگذارد. اگر مجوزهای میزبان برای این URL در فایل مانیفست مشخص نشده باشد، فراخوانی API با شکست مواجه خواهد شد.

    • ارزش

      رشته اختیاری

      مقدار کوکی. در صورت حذف، به طور پیش‌فرض خالی است.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (cookie?: Cookie) => void

    • کوکی

      کوکی اختیاری

      شامل جزئیاتی درباره کوکی تنظیم شده است. اگر تنظیم به هر دلیلی ناموفق باشد، promise رد خواهد شد.

بازگشت‌ها

  • قول < کوکی | تعریف نشده>

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها
onChanged 
chrome.cookies.onChanged.addListener(
  callback: function,
)

زمانی که یک کوکی تنظیم یا حذف می‌شود، اجرا می‌شود. به عنوان یک مورد خاص، توجه داشته باشید که به‌روزرسانی ویژگی‌های یک کوکی به عنوان یک فرآیند دو مرحله‌ای پیاده‌سازی می‌شود: کوکی که قرار است به‌روزرسانی شود، ابتدا به طور کامل حذف می‌شود و یک اعلان با "علت" "بازنویسی" ایجاد می‌شود. پس از آن، یک کوکی جدید با مقادیر به‌روزرسانی شده نوشته می‌شود و یک اعلان دوم با "علت" "صریح" ایجاد می‌کند.

پارامترها
  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (changeInfo: object) => void

    • تغییراطلاعات

      شیء

      • دلیل اصلی تغییر کوکی.

      • کوکی

        کوکی

        اطلاعات مربوط به کوکی که تنظیم یا حذف شده است.

      • حذف شده

        بولی

        اگر کوکی حذف شده باشد، درست است.