chrome.cookies

توضیحات

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

مجوزها

cookies

آشکار

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

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

پارتیشن بندی

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

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

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

نمونه ها

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

انواع

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

خواص

  • دامنه

    رشته

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

  • تاریخ انقضا

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

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

  • میزبان فقط

    بولی

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

  • فقط http

    بولی

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

  • نام

    رشته

    نام کوکی.

  • partitionKey

    CookiePartitionKey اختیاری است

    Chrome 119+

    کلید پارتیشن برای خواندن یا اصلاح کوکی ها با ویژگی Partitioned.

  • مسیر

    رشته

    مسیر کوکی.

  • همان سایت

    SameSiteStatus

    Chrome 51+

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

  • امن

    بولی

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

  • جلسه

    بولی

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

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

    رشته

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

  • ارزش

    رشته

    ارزش کوکی

CookieDetails

Chrome 88+

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

خواص

  • نام

    رشته

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

  • partitionKey

    CookiePartitionKey اختیاری است

    Chrome 119+

    کلید پارتیشن برای خواندن یا اصلاح کوکی ها با ویژگی Partitioned.

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

    رشته اختیاری

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

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

    رشته

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

CookiePartitionKey

Chrome 119+

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

خواص

  • دارای کراس‌سایت اجداد

    بولی اختیاری

    Chrome 130+

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

  • topLevelSite

    رشته اختیاری

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

CookieStore

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

خواص

  • شناسه

    رشته

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

  • tabIds

    شماره[]

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

FrameDetails

در انتظار

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

خواص

  • شناسه سند

    رشته اختیاری

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

  • frameId

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

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

  • tabId

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

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

OnChangedCause

Chrome 44+

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

Enum

"اخراجی"

"منقضی شده"

"صریح"

"expired_overwrite"

"بازنویسی"

SameSiteStatus

Chrome 51+

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

Enum

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

"سست"

"سخت"

"نامشخص"

روش ها

get()

قول بده
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

پارامترها

  • جزئیات

    جزئیات کوکی

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (cookie?: Cookie) => void

    • کوکی

      کوکی اختیاری است

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

برمی گرداند

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

    Chrome 88+

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

getAll()

قول بده
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

پارامترها

  • جزئیات

    شی

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

    • دامنه

      رشته اختیاری

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

    • نام

      رشته اختیاری

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

    • partitionKey

      CookiePartitionKey اختیاری است

      Chrome 119+

      کلید پارتیشن برای خواندن یا اصلاح کوکی ها با ویژگی Partitioned.

    • مسیر

      رشته اختیاری

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

    • امن

      بولی اختیاری

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

    • جلسه

      بولی اختیاری

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

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

      رشته اختیاری

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

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

      رشته اختیاری

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (cookies: Cookie[]) => void

    • کوکی ها

      کوکی []

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

برمی گرداند

  • وعده< کوکی []>

    Chrome 88+

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

getAllCookieStores()

قول بده
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (cookieStores: CookieStore[]) => void

برمی گرداند

  • Promise< CookieStore []>

    Chrome 88+

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

getPartitionKey()

وعده در انتظار
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

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

پارامترها

  • جزئیات

    جزئیات قاب

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (details: object) => void

    • جزئیات

      شی

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

      • partitionKey

        CookiePartitionKey

        کلید پارتیشن برای خواندن یا اصلاح کوکی ها با ویژگی Partitioned.

برمی گرداند

  • قول<object>

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

remove()

قول بده
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

پارامترها

  • جزئیات

    جزئیات کوکی

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (details?: object) => void

    • جزئیات

      شی اختیاری

      حاوی جزئیات مربوط به کوکی حذف شده است. اگر به هر دلیلی حذف نشد، "null" خواهد بود و runtime.lastError تنظیم می شود.

      • نام

        رشته

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

      • partitionKey

        CookiePartitionKey اختیاری است

        Chrome 119+

        کلید پارتیشن برای خواندن یا اصلاح کوکی ها با ویژگی Partitioned.

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

        رشته

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

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

        رشته

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

برمی گرداند

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

    Chrome 88+

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

set()

قول بده
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

پارامترها

  • جزئیات

    شی

    جزئیات در مورد کوکی در حال تنظیم.

    • دامنه

      رشته اختیاری

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

    • تاریخ انقضا

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

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

    • فقط http

      بولی اختیاری

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

    • نام

      رشته اختیاری

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

    • partitionKey

      CookiePartitionKey اختیاری است

      Chrome 119+

      کلید پارتیشن برای خواندن یا اصلاح کوکی ها با ویژگی Partitioned.

    • مسیر

      رشته اختیاری

      مسیر کوکی. قسمت مسیر پارامتر url را پیش‌فرض قرار می‌دهد.

    • همان سایت

      SameSiteStatus اختیاری است

      Chrome 51+

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

    • امن

      بولی اختیاری

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

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

      رشته اختیاری

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

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

      رشته

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

    • ارزش

      رشته اختیاری

      ارزش کوکی در صورت حذف به صورت پیش فرض خالی است.

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (cookie?: Cookie) => void

    • کوکی

      کوکی اختیاری است

      حاوی جزئیات مربوط به کوکی تنظیم شده است. اگر تنظیم به هر دلیلی ناموفق باشد، "null" خواهد بود و runtime.lastError تنظیم می شود.

برمی گرداند

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

    Chrome 88+

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

رویدادها

onChanged

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

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

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (changeInfo: object) => void

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

      شی

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

      • کوکی

        کوکی

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

      • حذف شده است

        بولی

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