chrome.cookies

الوصف

استخدِم واجهة برمجة التطبيقات chrome.cookies API لطلب ملفات تعريف الارتباط وتعديلها، وللحصول على إشعارات عند تغييرها.

الأذونات

cookies

البيان

لاستخدام واجهة برمجة التطبيقات Cookies API، يجب الإفصاح عن إذن "ملفات تعريف الارتباط" في بيان التطبيق، بالإضافة إلى أذونات المضيف لأي مضيفين تريد الوصول إلى ملفات تعريف الارتباط الخاصة بهم. على سبيل المثال:

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

التقسيم

تسمح ملفات تعريف الارتباط المُقسَّمة لموقع إلكتروني بوضع علامة على أنّه يجب ربط ملفات تعريف ارتباط معيّنة بملف تعريف الارتباط لإطار المستوى الأعلى. وهذا يعني أنّه إذا تمّ تضمين الموقع الإلكتروني "أ" باستخدام إطار iframe في الموقع الإلكتروني "ب" والموقع الإلكتروني "ج"، يمكن أن يكون لملفات تعريف الارتباط المقسّمة قيمة مختلفة في كلّ موقع.

لا تتيح chrome.cookies التقسيم، ما يعني أنّ جميع الطرق تقرأ ملفات تعريف الارتباط وتكتبها من جميع الأقسام. تخزِّن طريقة cookies.set() ملفات تعريف الارتباط في القسم التلقائي.

لمعرفة التفاصيل حول التأثير العام لتقسيم الإضافات، يُرجى الاطّلاع على مساحة التخزين وملفات تعريف الارتباط.

أمثلة

يمكنك العثور على مثال بسيط لاستخدام واجهة برمجة التطبيقات الخاصة بملفات تعريف الارتباط في الدليل examples/api/cookies. للحصول على أمثلة أخرى وللحصول على مساعدة في عرض رمز المصدر، يُرجى الاطّلاع على عيّنات.

الأنواع

Cookie

يمثّل معلومات عن ملف تعريف ارتباط HTTP.

أماكن إقامة

• نطاق

  سلسلة

  نطاق ملفّ تعريف الارتباط (مثل "www.google.com" أو "example.com")

• expirationDate

  رقم اختياري

  تاريخ انتهاء صلاحية ملفّ تعريف الارتباط بالتنسيق: عدد الثواني منذ بدء حساب الفترة بنظام التشغيل UNIX لا يتم توفيرها لملفات تعريف ارتباط الجلسة.

• hostOnly

  قيمة منطقية

  صحيح إذا كان ملف تعريف الارتباط خاصًا بالمضيف فقط (أي يجب أن يتطابق مضيف الطلب تمامًا مع نطاق ملف تعريف الارتباط).

• httpOnly

  قيمة منطقية

  صحيح إذا تم وضع علامة على ملف تعريف الارتباط على أنّه HttpOnly (أي لا يمكن الوصول إلى ملف تعريف الارتباط من خلال النصوص البرمجية من جهة العميل).

• الاسم

  سلسلة

  اسم ملفّ تعريف الارتباط.

• partitionKey

  ‫CookiePartitionKey اختياري

  الإصدار 119 من Chrome والإصدارات الأحدث

  مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

• المسار

  سلسلة

  مسار ملف تعريف الارتباط

• sameSite

  SameSiteStatus

  Chrome 51 والإصدارات الأحدث

  حالة ملف تعريف الارتباط على الموقع الإلكتروني نفسه (أي ما إذا كان يتم إرسال ملف تعريف الارتباط مع طلبات من مواقع إلكترونية مختلفة).

• آمن

  قيمة منطقية

  صحيح إذا تم وضع علامة على ملف تعريف الارتباط على أنّه آمن (أي أنّ نطاقه يقتصر على القنوات الآمنة، عادةً HTTPS).

• جلسة

  قيمة منطقية

  صحيح إذا كان ملف تعريف الارتباط هو ملف تعريف ارتباط للجلسة، على عكس ملف تعريف ارتباط دائم له تاريخ انتهاء صلاحية.

• storeId

  سلسلة

  معرّف مخزن ملفات تعريف الارتباط الذي يحتوي على ملف تعريف الارتباط هذا، كما هو موضّح في getAllCookieStores().

• القيمة

  سلسلة

  قيمة ملفّ تعريف الارتباط.

CookieDetails

الإصدار 88 من Chrome والإصدارات الأحدث

تفاصيل لتحديد ملف تعريف الارتباط

أماكن إقامة

• الاسم

  سلسلة

  اسم ملف تعريف الارتباط المطلوب الوصول إليه.

• partitionKey

  ‫CookiePartitionKey اختياري

  الإصدار 119 من Chrome والإصدارات الأحدث

  مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

• storeId

  سلسلة اختيارية

  رقم تعريف ذاكرة ملفات تعريف الارتباط التي يتم البحث فيها عن ملف تعريف الارتباط. سيتم تلقائيًا استخدام ذاكرة ملفات تعريف الارتباط لسياق التنفيذ الحالي.

• url

  سلسلة

  عنوان URL المرتبط بملف تعريف الارتباط المطلوب الوصول إليه. قد تكون هذه الوسيطة عنوان URL كاملاً، وفي هذه الحالة يتم ببساطة تجاهل أي بيانات تلي مسار عنوان URL (مثل سلسلة طلب البحث). إذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر طلب البيانات من واجهة برمجة التطبيقات.

CookiePartitionKey

الإصدار 119 من Chrome والإصدارات الأحدث

يمثّل مفتاح قسم ملف تعريف ارتباط مُقسَّم.

أماكن إقامة

• hasCrossSiteAncestor

  منطقي اختياري

  الإصدار 130 من Chrome والإصدارات الأحدث

  يشير إلى ما إذا تم ضبط ملف تعريف الارتباط في سياق مواقع إلكترونية متعددة. ويمنع ذلك الموقع الإلكتروني من المستوى الأعلى المضمّن في سياق على جميع المواقع الإلكترونية من الوصول إلى ملفات تعريف الارتباط التي ضبطها الموقع الإلكتروني من المستوى الأعلى في سياق الموقع الإلكتروني نفسه.

• topLevelSite

  سلسلة اختيارية

  الموقع الإلكتروني الأعلى مستوى الذي يتوفّر فيه ملفّ تعريف الارتباط المُقسَّم

CookieStore

يمثّل متجر ملفات تعريف الارتباط في المتصفّح. على سبيل المثال، تستخدم نافذة وضع التصفّح المتخفي متجر ملفات تعريف ارتباط منفصلاً عن نافذة غير مزوّدة بوضع التصفّح المتخفي.

أماكن إقامة

• id

  سلسلة

  المعرّف الفريد لمخزن ملفات تعريف الارتباط

• tabIds

  number[]

  معرّفات جميع علامات تبويب المتصفّح التي تشارك هذا المتجر لملفّات تعريف الارتباط

FrameDetails

في انتظار المراجعة

تفاصيل لتحديد الإطار

أماكن إقامة

• documentId

  سلسلة اختيارية

  المعرّف الفريد للمستند في حال تقديم frameId و/أو tabId، سيتم التحقّق من صحتهما للتطابق مع المستند الذي تم العثور عليه باستخدام معرّف المستند المقدَّم.

• frameId

  رقم اختياري

  المعرّف الفريد للإطار ضمن علامة التبويب

• tabId

  رقم اختياري

  المعرّف الفريد للعلامة التي تحتوي على الإطار

OnChangedCause

Chrome 44 والإصدارات الأحدث

السبب الأساسي لتغيير ملف تعريف الارتباط إذا تم إدراج ملف تعريف ارتباط أو إزالته من خلال طلب صريح إلى chrome.cookies.remove، سيكون السبب "واضحًا". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب انتهاء صلاحيته، سيكون "سبب" الإزالة هو "انتهت الصلاحية". إذا تمت إزالة ملف تعريف ارتباط بسبب استبداله بتاريخ انتهاء صلاحية انتهت صلاحيته، سيتم ضبط "سبب" على "expired_overwrite". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب جمع المهملات، سيتم "إخلاء" "سبب". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب طلب "set" الذي أعاد كتابته، سيكون "سبب" الإزالة هو "إعادة الكتابة". وخطِّط ردّك وفقًا لذلك.

التعداد

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 والإصدارات الأحدث

حالة ملف تعريف الارتباط "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,
)

تُستخدَم لاسترداد معلومات عن ملف تعريف ارتباط واحد. إذا كان هناك أكثر من ملف تعريف ارتباط واحد يحمل الاسم نفسه لعنوان URL المحدّد، سيتم عرض الملف الذي يتضمّن المسار الأطول. بالنسبة إلى ملفات تعريف الارتباط التي لها طول المسار نفسه، سيتم عرض ملف تعريف الارتباط الذي تم إنشاؤه في أقرب وقت.

المعلمات

• التفاصيل

  CookieDetails

• ردّ الاتصال

  الدالة اختيارية

  تظهر المَعلمة callback على النحو التالي:

  (cookie?: Cookie) => void

  • كعكة محلاة

    ملف تعريف الارتباط اختياري

    يحتوي على تفاصيل حول ملف تعريف الارتباط. تكون هذه المَعلمة فارغة في حال عدم العثور على ملفّ تعريف ارتباط من هذا النوع.

المرتجعات

• Promise<Cookie | undefined>

  الإصدار 88 من Chrome والإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

getAll()

الوعد

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

يسترجع جميع ملفات تعريف الارتباط من متجر ملفات تعريف ارتباط واحد تتطابق مع المعلومات المقدَّمة. سيتم ترتيب ملفات تعريف الارتباط التي يتم عرضها، مع عرض تلك التي لها المسار الأطول أولاً. إذا كانت هناك ملفات تعريف ارتباط متعددة لها طول المسار نفسه، ستكون ملفات تعريف الارتباط التي تم إنشاؤها في أقرب وقت هي الأولى. لا تستردّ هذه الطريقة سوى ملفات تعريف الارتباط للنطاقات التي تملك فيها الإضافة أذونات مضيف.

المعلمات

• التفاصيل

  عنصر

  معلومات لفلترة ملفات تعريف الارتباط التي يتم استرجاعها

  • نطاق

    سلسلة اختيارية

    يحصر ملفات تعريف الارتباط التي يتم استرجاعها بتلك التي تتطابق نطاقاتها مع هذا النطاق أو هي نطاقات فرعية منه.

  • الاسم

    سلسلة اختيارية

    تصفية ملفات تعريف الارتباط حسب الاسم

  • partitionKey

    ‫CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث

    مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

  • المسار

    سلسلة اختيارية

    يحصر ملفات تعريف الارتباط التي يتم استرجاعها بتلك التي يتطابق مسارها تمامًا مع هذه السلسلة.

  • آمن

    منطقي اختياري

    تصفية ملفات تعريف الارتباط حسب خاصيتها "آمنة"

  • جلسة

    منطقي اختياري

    فلترة ملفات تعريف الارتباط الخاصة بالجلسة مقابل ملفات تعريف الارتباط الثابتة

  • storeId

    سلسلة اختيارية

    متجر ملفات تعريف الارتباط لاسترداد ملفات تعريف الارتباط منه في حال حذف هذا العنصر، سيتم استخدام ملفّات تعريف الارتباط في سياق التنفيذ الحالي.

  • url

    سلسلة اختيارية

    حصر ملفات تعريف الارتباط التي يتم استرجاعها على تلك التي تتطابق مع عنوان URL المحدّد

• ردّ الاتصال

  الدالة اختيارية

  تظهر المَعلمة callback على النحو التالي:

  (cookies: Cookie[]) => void

  • ملفات تعريف الارتباط

    Cookie[]

    جميع ملفات تعريف الارتباط الحالية غير المنتهية الصلاحية التي تتطابق مع معلومات ملفّ تعريف الارتباط المحدّدة

المرتجعات

• Promise<Cookie[]>

  الإصدار 88 من Chrome والإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

getAllCookieStores()

الوعد

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

يسرد جميع متاجر ملفات تعريف الارتباط الحالية.

المعلمات

• ردّ الاتصال

  الدالة اختيارية

  تظهر المَعلمة callback على النحو التالي:

  (cookieStores: CookieStore[]) => void

  • cookieStores

    CookieStore[]

    كل متاجر ملفات تعريف الارتباط الحالية

المرتجعات

• Promise<CookieStore[]>

  الإصدار 88 من Chrome والإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

getPartitionKey()

الوعد في انتظار المراجعة

chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

مفتاح التقسيم للإطار المحدَّد

المعلمات

• التفاصيل

  FrameDetails

• ردّ الاتصال

  الدالة اختيارية

  تظهر المَعلمة callback على النحو التالي:

  (details: object) => void

  • التفاصيل

    عنصر

    يحتوي على تفاصيل عن مفتاح التقسيم الذي تم استرجاعه.

    • partitionKey

      CookiePartitionKey

      مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

المرتجعات

• Promise<object>

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

remove()

الوعد

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

لحذف ملف تعريف ارتباط حسب الاسم

المعلمات

• التفاصيل

  CookieDetails

• ردّ الاتصال

  الدالة اختيارية

  تظهر المَعلمة callback على النحو التالي:

  (details?: object) => void

  • التفاصيل

    العنصر اختياري

    يحتوي على تفاصيل عن ملف تعريف الارتباط الذي تمّت إزالته. إذا تعذّرت الإزالة لأي سبب، ستكون القيمة "null"، وسيتم ضبط runtime.lastError.

    • الاسم

      سلسلة

      اسم ملف تعريف الارتباط الذي تمت إزالته.

    • partitionKey

      ‫CookiePartitionKey اختياري

      الإصدار 119 من Chrome والإصدارات الأحدث

      مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

    • storeId

      سلسلة

      رقم تعريف ذاكرة تخزين ملفات تعريف الارتباط التي تمت إزالة ملف تعريف الارتباط منها.

    • url

      سلسلة

      عنوان URL المرتبط بملف تعريف الارتباط الذي تمت إزالته.

المرتجعات

• Promise<object | undefined>

  الإصدار 88 من Chrome والإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

set()

الوعد

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

تُستخدَم لضبط ملفّ تعريف ارتباط باستخدام بيانات ملفّ تعريف الارتباط المحدّدة، وقد تستبدِل ملفات تعريف الارتباط المماثلة في حال توفّرها.

المعلمات

• التفاصيل

  عنصر

  تفاصيل حول ملف تعريف الارتباط الذي يتمّ ضبطه

  • نطاق

    سلسلة اختيارية

    نطاق ملفّ تعريف الارتباط. في حال حذفه، يصبح ملف تعريف الارتباط ملفّ تعريف ارتباط للمضيف فقط.

  • expirationDate

    رقم اختياري

    تاريخ انتهاء صلاحية ملفّ تعريف الارتباط بالتنسيق: عدد الثواني منذ بدء حساب الفترة بنظام التشغيل UNIX في حال حذفه، يصبح ملف تعريف الارتباط ملفّ تعريف ارتباط للجلسة.

  • httpOnly

    منطقي اختياري

    ما إذا كان يجب وضع علامة على ملف تعريف الارتباط على أنّه HttpOnly القيمة التلقائية هي false.

  • الاسم

    سلسلة اختيارية

    اسم ملفّ تعريف الارتباط. فارغ تلقائيًا في حال حذفه

  • partitionKey

    ‫CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث

    مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

  • المسار

    سلسلة اختيارية

    مسار ملف تعريف الارتباط الإعداد التلقائي هو جزء المسار من مَعلمة عنوان URL.

  • sameSite

    ‫SameSiteStatus اختياري

    Chrome 51 والإصدارات الأحدث

    حالة ملف تعريف الارتباط على الموقع الإلكتروني نفسه يتم ضبط القيمة تلقائيًا على "غير محدّد"، أي في حال حذفها، يتم ضبط ملف تعريف الارتباط بدون تحديد سمة SameSite.

  • آمن

    منطقي اختياري

    ما إذا كان يجب وضع علامة على ملف تعريف الارتباط باعتباره آمنًا القيمة التلقائية هي false.

  • storeId

    سلسلة اختيارية

    رقم تعريف مخزن ملفات تعريف الارتباط الذي سيتم ضبط ملف تعريف الارتباط فيه. يتم ضبط ملف تعريف الارتباط تلقائيًا في ذاكرة ملفات تعريف الارتباط لسياق التنفيذ الحالي.

  • url

    سلسلة

    معرّف الموارد المنتظم للطلب لربطه بإعداد ملف تعريف الارتباط يمكن أن تؤثر هذه القيمة في قيم النطاق والمسار التلقائيَين لملف تعريف الارتباط الذي تم إنشاؤه. إذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر طلب البيانات من واجهة برمجة التطبيقات.

  • القيمة

    سلسلة اختيارية

    قيمة ملفّ تعريف الارتباط. فارغ تلقائيًا في حال حذفه

• ردّ الاتصال

  الدالة اختيارية

  تظهر المَعلمة callback على النحو التالي:

  (cookie?: Cookie) => void

  • كعكة محلاة

    ملف تعريف الارتباط اختياري

    يحتوي على تفاصيل حول ملف تعريف الارتباط الذي تم ضبطه. إذا تعذّر ضبط الإعداد لأي سبب، ستكون القيمة "null"، وسيتم ضبط runtime.lastError.

المرتجعات

• Promise<Cookie | undefined>

  الإصدار 88 من Chrome والإصدارات الأحدث

  لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

الفعاليات

onChanged

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

يتم تشغيله عند ضبط ملف تعريف ارتباط أو إزالته. في حال حدوث حالة خاصة، يُرجى العِلم أنّ تعديل سمات ملفّ تعريف الارتباط يتمّ من خلال عمليتين: أولاً، تتمّ إزالة ملفّ تعريف الارتباط الذي سيتمّ تعديله بالكامل، ما يؤدي إلى إنشاء إشعار يتضمن "سبب" "الاستبدال" . بعد ذلك، يتمّ إنشاء ملف تعريف ارتباط جديد بالقيم المعدّلة، ما يؤدّي إلى إنشاء إشعار ثانٍ بالقيمة "explicit" للسبب.

المعلمات

• ردّ الاتصال

  دالة

  تظهر المَعلمة callback على النحو التالي:

  (changeInfo: object) => void

  • changeInfo

    عنصر

    • السبب

      OnChangedCause

      السبب الأساسي لتغيير ملف تعريف الارتباط

    • كعكة محلاة

      Cookie

      معلومات عن ملفّ تعريف الارتباط الذي تمّ ضبطه أو إزالته

    • تمت الإزالة

      قيمة منطقية

      صحيح إذا تمّت إزالة ملفّ تعريف ارتباط.