دليل مطوّري Topics API

تعرَّف على طريقة العمل مع واجهة برمجة التطبيقات، بما في ذلك طريقة استخدام علامات Chrome للاختبار.

حالة التنفيذ

تجربة العرض التوضيحي

يتوفّر إصداران تجريبيان من Topics API يسمحان لك بتجربة Topics كمستخدم واحد.

يمكنك أيضًا تنفيذ ميزة التعاون في المواضيع لتجربة نموذج مصنّف المواضيع.

استخدام واجهة برمجة تطبيقات 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.

يمكن الوصول إلى المواضيع من عنوان 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.

صفحة chrome://topics-internals مع اختيار لوحة &quot;حالة المواضيع&quot;.
تعرض لوحة "حالة المواضيع" في صفحة chrome://topics-internals معرّفات المواضيع والمهام العشوائية والحقيقية وإصدارات التصنيفات وإصدارات النماذج.

توضّح لقطة الشاشة هذه أنّ المواقع الإلكترونية التي تمت زيارتها مؤخرًا تشمل topics-demo-cats.glitch.me وcats-cats-cats-cats.glitch.me. يؤدي ذلك إلى اختيار Topics API Pets وCats باعتبارهما موضوعَين من أهم المواضيع في الفترة الحالية. لقد تم اختيار المواضيع الثلاثة المتبقية عشوائيًا، لأنّه لا يتوفّر سجلّ تصفّح كافٍ (على المواقع الإلكترونية التي ترصد المواضيع) لتقديم خمسة مواضيع.

ويوفّر عمود نطاقات السياق المرصودة (المجزأة) القيمة المجزّأة لاسم المضيف الذي تمت ملاحظة موضوع له.

عرض المواضيع التي تم استنتاجها لأسماء المضيفين

يمكنك أيضًا عرض المواضيع التي تم استنتاجها من خلال نموذج مصنِّف "المواضيع" لاسم مضيف واحد أو أكثر في "chrome://topics-internals".

صفحة chrome://topics-internals مع اختيار لوحة &quot;المصنِّف&quot;.
تعرض لوحة "المصنِّف" في صفحة 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-internals صفحة chrome://topics-internals مع اختيار لوحة الميزات والمَعلمات
تعرض لوحة الميزات والمَعلمات في chrome://topics-internals الميزات المفعَّلة والوقت لكل حقبة وعدد الفترات المطلوب استخدامها لاحتساب المواضيع وإصدار التصنيف وغير ذلك من الإعدادات.

تتطابق المَعلمات المعروضة في لقطة الشاشة مع العلامات التي يمكن ضبطها عند تشغيل 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")

الخطوات التالية

التعرف على المزيد

التفاعل مع الملاحظات ومشاركتها