chrome.cookies

شرح

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

مجوزها

cookies

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

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

پارتیشن بندی

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

به طور پیش‌فرض، همه روش‌های API روی کوکی‌های پارتیشن نشده کار می‌کنند. از ویژگی partitionKey می توان برای نادیده گرفتن این رفتار استفاده کرد.

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

مثال ها

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

انواع

Cookie

نشان دهنده اطلاعات یک کوکی 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+

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

خواص

• topLevelSite

  رشته اختیاری

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

CookieStore

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

خواص

• شناسه

  رشته

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

• tabIds

  عدد[]

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

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

  • کوکی

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

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

برمی گرداند

• Promise< کوکی |undefined>

  Chrome 88+

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

getAll()

وعده

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

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

مولفه های

• جزئیات

  هدف - شی

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

  • دامنه

    رشته اختیاری

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

  • نام

    رشته اختیاری

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

  • partitionKey

    CookiePartitionKey اختیاری است

    Chrome 119+

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

  • مسیر

    رشته اختیاری

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

  • امن است

    بولی اختیاری

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

  • جلسه

    بولی اختیاری

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

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

    رشته اختیاری

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

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

    رشته اختیاری

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

• پاسخ به تماس

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

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

  (cookies: Cookie[])=>void

  • بیسکویت ها

    کوکی []

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

برمی گرداند

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

  Chrome 88+

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

getAllCookieStores()

وعده

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

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

مولفه های

• پاسخ به تماس

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

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

  (cookieStores: CookieStore[])=>void

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

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

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

برمی گرداند

• Promise< CookieStore []>

  Chrome 88+

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

remove()

وعده

chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

مولفه های

• جزئیات

  جزئیات کوکی

• پاسخ به تماس

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

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

  (details?: object)=>void

  • جزئیات

    شی اختیاری

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

    • نام

      رشته

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

    • partitionKey

      CookiePartitionKey اختیاری است

      Chrome 119+

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

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

      رشته

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

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

      رشته

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

برمی گرداند

• وعده<object|undefined>

  Chrome 88+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به 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 تنظیم می شود.

برمی گرداند

• Promise< کوکی |undefined>

  Chrome 88+

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

مناسبت ها

onChanged

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

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

مولفه های

• پاسخ به تماس

  تابع

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

  (changeInfo: object)=>void

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

    هدف - شی

    • علت

      OnChangedCause

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

    • کوکی

      کوکی

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

    • حذف شده

      بولی

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