chrome.cookies

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.cookies API برای پرسمان و اصلاح کوکی‌ها و دریافت اعلان هنگام تغییر آن‌ها استفاده کنید.

اجازه‌ها

cookies

مانیفست

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

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

پارتیشن‌بندی

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

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

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

مثال‌ها

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

انواع

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

مشخصات

  • دامنه

    رشته

    دامنه کوکی (برای مثال، «www.google.com»، «example.com»).

  • expirationDate

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

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

  • hostOnly

    بولی

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

  • httpOnly

    بولی

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

  • نام

    رشته

    نام کوکی.

  • partitionKey

    CookiePartitionKey اختیاری

    Chrome نسخه ۱۱۹ به بالا

    کلید پارتیشن برای خواندن یا اصلاح کوکی‌ها با مشخصه «تفکیک‌شده».

  • مسیر

    رشته

    مسیر کوکی.

  • sameSite

    SameSiteStatus

    Chrome نسخه ۵۱ به بالا

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

  • ایمن کردن

    بولی

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

  • جلسه

    بولی

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

  • storeId

    رشته

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

  • مقدار

    رشته

    مقدار کوکی.

CookieDetails

Chrome نسخه ۸۸ و بالاتر

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

مشخصات

  • نام

    رشته

    نام کوکی برای دسترسی.

  • partitionKey

    CookiePartitionKey اختیاری

    Chrome نسخه ۱۱۹ به بالا

    کلید پارتیشن برای خواندن یا اصلاح کوکی‌ها با مشخصه «تفکیک‌شده».

  • storeId

    رشته اختیاری

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

  • نشانی وب

    رشته

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

CookiePartitionKey

Chrome نسخه ۱۱۹ به بالا

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

مشخصات

  • hasCrossSiteAncestor

    بولی اختیاری

    Chrome نسخه ۱۳۰ و بالاتر

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

  • topLevelSite

    رشته اختیاری

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

CookieStore

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

مشخصات

  • id

    رشته

    شناسه یکتای فروشگاه کوکی.

  • tabIds

    عدد[]

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

FrameDetails

Chrome نسخه ۱۳۲ و بالاتر

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

مشخصات

  • documentId

    رشته اختیاری

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

  • frameId

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

    شناسه یکتای قاب در برگه.

  • tabId

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

    شناسه یکتای برگه‌ای که حاوی قاب است.

OnChangedCause

Chrome نسخه ۴۴ به بالا

دلیل اصلی تغییر کوکی. اگر کوکی‌ای ازطریق فراخوانی صریح به «chrome.cookies.remove» درج یا برداشته شده باشد، «علت» «صریح» خواهد بود. اگر کوکی به‌دلیل انقضا به‌طور خودکار برداشته شده باشد، «علت» «منقضی‌شده» خواهد بود. اگر کوکی به‌دلیل رونویسی شدن با تاریخ انقضای ازقبل منقضی‌شده برداشته شده باشد، «علت» روی «expired_overwrite» تنظیم خواهد شد. اگر کوکی به‌دلیل جمع‌آوری زباله به‌طور خودکار برداشته شده باشد، «علت» آن «اخراج» خواهد بود. اگر کوکی به‌طور خودکار به‌دلیل فراخوانی «تنظیم» که آن را رونویسی کرده است برداشته شده باشد، «علت» «رونویسی» خواهد بود. پاسختان را براین‌اساس برنامه‌ریزی کنید.

شمارشی

"evicted"

«منقضی‌شده»

«صریح»

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome نسخه ۵۱ به بالا

وضعیت «SameSite» کوکی (https://tools.ietf.org/html/draft-west-first-party-cookies). ‫«no_restriction» با کوکی تنظیم‌شده با «SameSite=None»،‏ «lax» با «SameSite=Lax»، و «strict» با «SameSite=Strict» مطابقت دارد. «نامشخص» با کوکی تنظیم‌شده بدون شاخصه SameSite مطابقت دارد.

شمارشی

"no_restriction"

«lax»

"strict"

"unspecified"

روش‌ها

get()

قول 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

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

پارامترها

  • جزئیات

    CookieDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (cookie?: Cookie) => void

    • کوکی

      کوکی اختیاری

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

بازگشتی‌ها

  • Promise<Cookie | undefined>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getAll()

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

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

پارامترها

  • جزئیات

    شیء

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

    • دامنه

      رشته اختیاری

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

    • نام

      رشته اختیاری

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

    • partitionKey

      CookiePartitionKey اختیاری

      Chrome نسخه ۱۱۹ به بالا

      کلید پارتیشن برای خواندن یا اصلاح کوکی‌ها با مشخصه «تفکیک‌شده».

    • مسیر

      رشته اختیاری

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

    • ایمن کردن

      بولی اختیاری

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

    • جلسه

      بولی اختیاری

      کوکی‌های جلسه را از کوکی‌های پایدار فیلتر می‌کند.

    • storeId

      رشته اختیاری

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

    • نشانی وب

      رشته اختیاری

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (cookies: Cookie[]) => void

    • کوکی‌ها

      کوکی[]

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

بازگشتی‌ها

  • Promise<Cookie[]>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getAllCookieStores()

قول 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

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

بازگشتی‌ها

  • Promise<CookieStore[]>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getPartitionKey()

Promise Chrome 132+ 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

کلید پارتیشن برای قاب نشان داده شده است.

پارامترها

  • جزئیات

    FrameDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (details: object) => void

    • جزئیات

      شیء

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

      • partitionKey

        CookiePartitionKey

        کلید پارتیشن برای خواندن یا اصلاح کوکی‌ها با مشخصه «تفکیک‌شده».

بازگشتی‌ها

  • Promise<object>

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

remove()

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

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

پارامترها

  • جزئیات

    CookieDetails

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (details?: object) => void

    • جزئیات

      شیء اختیاری

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

      • نام

        رشته

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

      • partitionKey

        CookiePartitionKey اختیاری

        Chrome نسخه ۱۱۹ به بالا

        کلید پارتیشن برای خواندن یا اصلاح کوکی‌ها با مشخصه «تفکیک‌شده».

      • storeId

        رشته

        شناسه فروشگاه کوکی که کوکی از آن برداشته شده است.

      • نشانی وب

        رشته

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

بازگشتی‌ها

  • Promise<object | undefined>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

set()

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

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

پارامترها

  • جزئیات

    شیء

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

    • دامنه

      رشته اختیاری

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

    • expirationDate

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

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

    • httpOnly

      بولی اختیاری

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

    • نام

      رشته اختیاری

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

    • partitionKey

      CookiePartitionKey اختیاری

      Chrome نسخه ۱۱۹ به بالا

      کلید پارتیشن برای خواندن یا اصلاح کوکی‌ها با مشخصه «تفکیک‌شده».

    • مسیر

      رشته اختیاری

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

    • sameSite

      SameSiteStatus اختیاری

      Chrome نسخه ۵۱ به بالا

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

    • ایمن کردن

      بولی اختیاری

      آیا کوکی باید به‌عنوان «ایمن» علامت‌گذاری شود یا نه. پیش‌فرض: نادرست.

    • storeId

      رشته اختیاری

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

    • نشانی وب

      رشته

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

    • مقدار

      رشته اختیاری

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (cookie?: Cookie) => void

    • کوکی

      کوکی اختیاری

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

بازگشتی‌ها

  • Promise<Cookie | undefined>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (changeInfo: object) => void

    • changeInfo

      شیء

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

      • کوکی

        کوکی

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

      • حذف شد

        بولی

        اگر کوکی برداشته شده باشد، True است.