تعرَّف على طريقة العمل مع واجهة برمجة التطبيقات، بما في ذلك طريقة استخدام علامات Chrome للاختبار.
حالة التنفيذ
- أكملت Topics API مرحلة المناقشة العلنية وهي متاحة حاليًا لنسبة 99 بالمائة من المستخدمين وبنسبة تصل إلى 100 بالمائة.
- لتقديم ملاحظاتك وآرائك حول Topics API، يمكنك إنشاء مشكلة في المواضيع التوضيحية أو المشاركة في المناقشات في مجموعة أعمال تحسين الإعلانات على الويب. يحتوي التفسير على عدد من الأسئلة المفتوحة التي لا تزال تتطلب تعريفًا إضافيًا.
- يوفّر المخطط الزمني لـ "مبادرة حماية الخصوصية" مخططات زمنية لتنفيذ Topics API وغيرها من اقتراحات "مبادرة حماية الخصوصية".
- Topics API: تعرض آخر التحديثات التغييرات والتحسينات التي طرأت على Topics API وعمليات التنفيذ.
تجربة العرض التوضيحي
يتوفّر إصداران تجريبيان من Topics API يسمحان لك بتجربة Topics كمستخدم واحد.
- عرض توضيحي لواجهة برمجة تطبيقات JavaScript: topics-demo.glitch.me
- عرض توضيحي للعنوان: topics-fetch-demo.glitch.me
يمكنك أيضًا تنفيذ ميزة التعاون في المواضيع لتجربة نموذج مصنّف المواضيع.
استخدام واجهة برمجة تطبيقات JavaScript للوصول إلى المواضيع وتسجيلها على النحو المرصود
تتضمن Topics JavaScript API طريقة واحدة: document.browsingTopics()
. ويهدف ذلك إلى غرضين:
- اطلب من المتصفح تسجيل زيارة الصفحة الحالية على أنها قد تمت ملاحظتها للمتصل، حتى يمكن استخدام ذلك لاحقًا لحساب المواضيع للمستخدم (بالنسبة إلى المتصل).
- الوصول إلى المواضيع التي لاحظها المتصل
تعرض هذه الطريقة وعدًا يحلّ مصفوفة مكوّنة من ثلاثة مواضيع، موضوع واحد لكل من أحدث حقبات، بترتيب عشوائي. الفترة هي فترة زمنية، يتم ضبطها على أسبوع واحد في تنفيذ Chrome.
يحتوي كل عنصر موضوع في الصفيف الذي يعرضه document.browsingTopics()
على السمات التالية:
configVersion
: سلسلة تحدِّد إعدادات Topics API الحالية، على سبيل المثالchrome.2
modelVersion
: سلسلة تحدّد مصنِّف تكنولوجيا تعلُّم الآلة المستخدَم لاستنتاج مواضيع الموقع الإلكتروني، على سبيل المثال4
taxonomyVersion
: سلسلة تحدّد مجموعة المواضيع التي يستخدمها المتصفّح، على سبيل المثال2
topic
: رقم يحدد الموضوع في التصنيف، على سبيل المثال309
version
: سلسلة تربطconfigVersion
وtaxonomyVersion
وmodelVersion
، على سبيل المثالchrome.2:2:4
إنّ المَعلمات الموضّحة في هذا الدليل وتفاصيل واجهة برمجة التطبيقات (مثل حجم التصنيف وعدد المواضيع التي يتم احتسابها كل أسبوع وعدد المواضيع التي يتم عرضها في كل مكالمة) عرضة للتغيير، لأنّنا ندمج ملاحظات المنظومة المتكاملة ونحسّنها باستمرار.
اكتشاف الدعم لـ document.browsingTopics
قبل استخدام واجهة برمجة التطبيقات، تحقّق مما إذا كانت متوافقة مع المتصفّح ومتاحة في المستند:
'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() is not supported on this page');
الوصول إلى المواضيع باستخدام JavaScript API
إليك مثال أساسي على الاستخدام المحتمل لواجهة برمجة التطبيقات للوصول إلى مواضيع المستخدم الحالي.
try {
// Get the array of top topics for this user.
const topics = await document.browsingTopics();
// Request an ad creative, providing topics information.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})
// Get the JSON from the response.
const creative = await response.json();
// Display ad.
} catch (error) {
// Handle error.
}
الوصول إلى المواضيع بدون تعديل الحالة
تعرض دالة document.browsingTopics()
المواضيع التي رصدها المتصل للمستخدم الحالي. وبشكل تلقائي، تجعل هذه الطريقة أيضًا المتصفِّح يسجِّل زيارة الصفحة الحالية على النحو الذي يلاحظه المتصل، وبالتالي يمكن استخدامها لاحقًا في حساب المواضيع. بدءًا من الإصدار 108 من Chrome، يمكن تمرير وسيطة اختيارية للطريقة لتخطي زيارة الصفحة من التسجيل: {skipObservation:true}
.
بمعنى آخر، تعني {skipObservation:true}
أنّ استدعاء الطريقة لن يؤدي إلى تضمين الصفحة الحالية في حساب المواضيع.
استخدام العناوين للوصول إلى المواضيع ووضع علامة عليها على أنّها تم رصدها
يمكنك الوصول إلى المواضيع، ووضع علامة على زيارات الصفحة أيضًا على أنّها يتم رصدها، وذلك بمساعدة عنوانَي الطلب والاستجابة.
قد يكون استخدام أسلوب العنوان أكثر فعالية من استخدام واجهة برمجة تطبيقات JavaScript، لأنّ واجهة برمجة التطبيقات تتطلّب إنشاء إطار iframe من مصادر متعددة وإجراء طلب document.browsingTopics()
منه. (يجب استخدام إطار iframe متعدد المصادر للاستدعاء، لأنّ السياق الذي يتم استدعاء واجهة برمجة التطبيقات منه يتم استخدامه لضمان عرض المتصفِّح للمواضيع المناسبة للمتصل). تمت مناقشة المزيد من المواضيع في مقالة "المواضيع" التوضيحية: هل يجب أن تكون هناك طريقة لإرسال المواضيع باستخدام ميزة "الجلب مثل عنوان الطلب"؟ .
يمكن الوصول إلى المواضيع من عنوان Sec-Browsing-Topics
لأحد الطلبات المستندة إلى fetch()
أو XHR
.
يؤدي ضبط عنوان Observe-Browsing-Topics: ?1
في الاستجابة للطلب إلى تسجيل المتصفّح لزيارة الصفحة الحالية على النحو الذي يلاحظه المتصل، وبالتالي يمكن استخدامه لاحقًا في احتساب المواضيع.
يمكن الوصول إلى المواضيع ومراقبتها باستخدام عناوين HTTP بطريقتَين:
fetch()
: أضِف{browsingTopics: true}
إلى معلَمة الخيارات لطلبfetch()
. يعرض العرض التوضيحي لعنوان المواضيع مثالاً مبسّطًا على ذلك.- سمة iframe: أضِف السمة
browsingtopics
إلى عنصر<iframe>
أو اضبط خاصية JavaScript المكافئةiframe.browsingTopics = true
. النطاق القابل للتسجيل لمصدر iframe هو نطاق المتصل، على سبيل المثال، بالنسبة إلى<iframe src="https://example.com" browsingtopics></iframe>
: المتصل هوexample.com
.
بعض الملاحظات الإضافية حول العناوين:
- ستتم متابعة عمليات إعادة التوجيه، وستكون المواضيع المرسلة في طلب إعادة التوجيه خاصة بعنوان URL لإعادة التوجيه.
- ولن يُعدِّل عنوان الطلب حالة المتصل ما لم يكن هناك عنوان استجابة مقابل. ويعني هذا أنّه بدون عنوان الاستجابة، لن يتم تسجيل زيارة الصفحة على النحو الذي تم رصده، وبالتالي لن تؤثر في حساب موضوع المستخدِم للفترة التالية.
- يتم قبول عنوان الاستجابة فقط إذا كان الطلب المقابل يتضمن عنوان المواضيع.
- يوفّر عنوان URL للطلب النطاق القابل للتسجيل الذي يتم تسجيله كنطاق المتصل.
تصحيح الأخطاء في تنفيذ واجهة برمجة التطبيقات
تتوفّر صفحة chrome://topics-internals
في متصفّح Chrome على أجهزة الكمبيوتر المكتبي بعد تفعيل Topics API. ويعرض هذا المواضيع للمستخدم الحالي والمواضيع المستخلصة من أسماء المضيفين ومعلومات فنية عن تنفيذ واجهة برمجة التطبيقات. نعمل على تكرار تصميم الصفحة وتحسينه استنادًا إلى ملاحظات المطوّرين. يمكنك إضافة ملاحظاتك على bugs.chromium.org.
عرض المواضيع التي يتم احتسابها للمتصفّح الذي تستخدمه
يمكن للمستخدمين الاطّلاع على معلومات حول المواضيع التي تمت ملاحظتها في المتصفّح خلال الحقبات الحالية والسابقة من خلال الاطّلاع على chrome://topics-internals
.
توضّح لقطة الشاشة هذه أنّ المواقع الإلكترونية التي تمت زيارتها مؤخرًا تشمل topics-demo-cats.glitch.me
وcats-cats-cats-cats.glitch.me
. يؤدي ذلك إلى اختيار Topics API Pets
وCats
باعتبارهما موضوعَين من أهم المواضيع في الفترة الحالية. لقد تم اختيار المواضيع الثلاثة المتبقية عشوائيًا، لأنّه لا يتوفّر سجلّ تصفّح كافٍ (على المواقع الإلكترونية التي ترصد المواضيع) لتقديم خمسة مواضيع.
ويوفّر عمود نطاقات السياق المرصودة (المجزأة) القيمة المجزّأة لاسم المضيف الذي تمت ملاحظة موضوع له.
عرض المواضيع التي تم استنتاجها لأسماء المضيفين
يمكنك أيضًا عرض المواضيع التي تم استنتاجها من خلال نموذج مصنِّف "المواضيع" لاسم مضيف واحد أو أكثر في "chrome://topics-internals
".
يستنتج التطبيق الحالي لـ Topics API المواضيع من أسماء المضيفين فقط، وليس من أي جزء آخر من عنوان URL.
استخدِم أسماء المضيفين فقط (بدون بروتوكول أو مسار) لعرض المواضيع المستنتَجة من مصنِّف chrome://topics-internals
. وسيعرض chrome://topics-internals
رسالة خطأ إذا حاولت تضمين "/" في الحقل Host (المضيف).
عرض معلومات Topics API
يمكنك العثور على معلومات عن تنفيذ Topics API وإعداداتها، مثل إصدار التصنيف ومدة الحقبة في chrome://topics-internals
. تعكس هذه القيم الإعدادات التلقائية لواجهة برمجة التطبيقات أو المعلَمات التي تم ضبطها بنجاح من سطر الأوامر. وقد يكون ذلك مفيدًا في تأكيد عمل علامات سطر الأوامر على النحو المتوقَّع.
في المثال، تمّ ضبط المدة time_period_per_epoch
على 15 ثانية (المدة التلقائية هي سبعة أيام).
تتطابق المَعلمات المعروضة في لقطة الشاشة مع العلامات التي يمكن ضبطها عند تشغيل Chrome من سطر الأوامر. على سبيل المثال، يقترح العرض التوضيحي المتوفّر على topics-fetch-demo.glitch.me استخدام العلامات التالية:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
توضّح القائمة التالية كل معلَمة وقيمتها التلقائية والغرض منها.
علامات Chrome
BrowsingTopics
- القيمة التلقائية:مفعَّلة
- ما إذا كانت Topics API مفعّلة أم لا.
PrivacySandboxAdsAPIsOverride
- القيمة التلقائية: مفعّلة
- تفعيل واجهات برمجة تطبيقات الإعلانات: Attribution Reporting وProtected Audience وTopics وFenced Frames.
PrivacySandboxSettings4
- القيمة التلقائية: غير مفعّلة
- يفعّل الإصدار الرابع من "مبادرة حماية الخصوصية".
OverridePrivacySandboxSettingsLocalTesting
- القيمة التلقائية:مفعَّلة
- في حال تفعيل هذه السياسة، لم يعُد المتصفّح يتطلب تفعيل الإعدادات الأساسية من أجل تفعيل ميزات "مبادرة حماية الخصوصية".
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- القيمة التلقائية: غير مفعَّلة
- في حال تفعيل هذا الإعداد، سيتم تجاوز عملية التحقّق ممّا إذا كان عنوان IP قابلاً للتوجيه للجميع عند تحديد أهلية الصفحة لتضمينها في عملية احتساب المواضيع.
BrowsingTopics:number_of_epochs_to_expose
- القيمة التلقائية: 3
- عدد الفترات التي يجب حساب المواضيع فيها لمنحها لسياق الطلب. وسيحتفظ المتصفح داخليًا بما يصل إلى حقبة N+1.
BrowsingTopics:time_period_per_epoch
- القيمة التلقائية: 7d-0h-0m-0s
- مدة كل حقبة. لتصحيح الأخطاء، قد يكون من المفيد ضبط هذه المدة على 15 ثانية (على سبيل المثال)، بدلاً من الأيام السبعة التلقائية.
BrowsingTopics:number_of_top_topics_per_epoch
- القيمة التلقائية: 5
- عدد المواضيع التي يتم احتسابها لكل حقبة.
BrowsingTopics:use_random_topic_probability_percent
- القيمة التلقائية: 5
- احتمالية ظهور موضوع فردي في فترة ما بشكل عشوائي من خلال تصنيف المواضيع بالكامل. وتكون العشوائية ثابتة في حقبة وموقع.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- القيمة التلقائية: 3
- عدد فترات بيانات استخدام واجهة برمجة التطبيقات (أي ملاحظات المواضيع) التي سيتم استخدامها لفلترة المواضيع لسياق الاتصال.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- القيمة التلقائية: 1,000
- الحد الأقصى لعدد النطاقات التي يتم تتبّعها حسب السياق والمطلوب الاحتفاظ بها لكل موضوع مهم. والغرض منه هو الحد من الذاكرة المستخدمة.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- القيمة التلقائية: 100,000
- الحد الأقصى لعدد الإدخالات المسموح باستردادها من قاعدة البيانات لكل طلب بحث في سياقات استخدام واجهة برمجة التطبيقات. سيظهر الاستعلام مرة واحدة لكل حقبة في وقت حساب المواضيع. والغرض منه هو تحديد الحد الأقصى لاستخدام الذاكرة.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- القيمة التلقائية: 30
- الحد الأقصى لعدد نطاقات سياق استخدام واجهة برمجة التطبيقات المسموح بتخزينها في كل تحميل للصفحة.
BrowsingTopics:config_version
- القيمة التلقائية: 1
- ترميز مَعلمات ضبط Topics API يجب ربط كل رقم إصدار
بمجموعة ضبط واحدة فقط من المفترض عادةً أن يكون تعديل مَعلمات الإعداد بدون تحديث
config_version
مناسبًا للاختبار المحلي، ولكن في بعض الحالات، قد يؤدي ذلك إلى ترك المتصفِّح في حالة غير متسقة وقد يؤدي إلى تعطُّل فيه، مثل تحديثnumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- القيمة التلقائية: 1
- إصدار التصنيف الذي تستخدمه واجهة برمجة التطبيقات.
إيقاف موقعك الإلكتروني
يمكنك إيقاف احتساب المواضيع لصفحات معيّنة على موقعك الإلكتروني من خلال تضمين العنوان Permissions-Policy: browsing-topics=()
سياسة الأذونات في صفحة معيّنة لمنع احتساب المواضيع لجميع المستخدمين في تلك الصفحة فقط. لن تتأثّر الزيارات اللاحقة إلى الصفحات الأخرى على موقعك الإلكتروني: إذا ضبطت سياسة لحظر Topics API على إحدى الصفحات، لن يؤثّر ذلك في الصفحات الأخرى.
يمكنك أيضًا التحكّم في الجهات الخارجية التي يمكنها الوصول إلى المواضيع على صفحتك باستخدام عنوان Permissions-Policy
للتحكّم في وصول الجهات الخارجية إلى Topics API. كمَعلمات في العنوان، استخدِم self
وأي نطاقات تريد السماح لها بالوصول إلى واجهة برمجة التطبيقات. على سبيل المثال، لإيقاف استخدام Topics API تمامًا في جميع سياقات التصفُّح باستثناء المصدر الخاص بك وhttps://example.com
، يمكنك ضبط عنوان استجابة HTTP التالي:
Permissions-Policy: browsing-topics=(self "https://example.com")
الخطوات التالية
- اطّلِع على مزيد من المعلومات حول المواضيع وآلية عملها.
- ننصحك بتجربة العرض التوضيحي.
التعرف على المزيد
التفاعل مع الملاحظات ومشاركتها
- GitHub: يمكنك الاطّلاع على الشرح الخاص بـ Topics API وطرح الأسئلة ومتابعة النقاشات بشأن المشاكل في مستودع واجهة برمجة التطبيقات.
- W3C: مناقشة حالات الاستخدام في المجال من خلال Optimize Web Advertising Business Group.
- الإشعارات: الانضمام إلى القائمة البريدية أو الاطّلاع عليها.
- دعم مطوّري برامج "مبادرة حماية الخصوصية": يمكنك طرح الأسئلة والمشاركة في النقاشات في مستودع دعم مطوّري برامج "مبادرة حماية الخصوصية".
- Chromium: يمكنك الإبلاغ عن خطأ في Chromium لطرح أسئلة حول طريقة التنفيذ المتاحة حاليًا في Chrome.