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

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

حالة التنفيذ

النسخة التجريبية

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

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

استخدام JavaScript API للوصول إلى المواضيع وتسجيلها على النحو الذي تم تتبّعه

تستخدم واجهة برمجة تطبيقات JavaScript Topics طريقة واحدة: 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() المواضيع التي لاحظها المتصل للمستخدم الحالي. وبشكل تلقائي، تؤدي هذه الطريقة أيضًا إلى تسجيل المتصفّح لزيارة الصفحة الحالية كما يلاحظها المتصل، لكي يتم استخدامها لاحقًا في احتساب المواضيع. من الإصدار Chrome 108، يمكن تمرير الطريقة وسيطة اختيارية لتخطّي تسجيل زيارة الصفحة: {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".

صفحة chrome://topics-internals التي تم فيها اختيار لوحة حالة المواضيع.
تعرض لوحة Topics State (حالة المواضيع) في صفحة chrome://topics-internals أرقام تعريف المواضيع، وعمليات تخصيص المواضيع العشوائية والفعلية، وإصدارات التصنيف والنموذج.

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

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

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

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

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

ويستنتج التنفيذ الحالي لواجهة Topics API المواضيع من أسماء المضيفين فقط. وليس من أي جزء آخر من عنوان URL

استخدِم أسماء المضيفين فقط (بدون بروتوكول أو مسار) لعرض المواضيع المستنتَجة من مصنِّف chrome://topics-internals. سيعرض chrome://topics-internals رسالة خطأ إذا حاولت تضمين "/". في حقل المضيف.

عرض معلومات Topics API

يمكنك العثور على معلومات عن تنفيذ Topics API وإعداداتها، مثل إصدار التصنيف ومدة الفترة، في chrome://topics-internals. وتعكس هذه القيم الإعدادات التلقائية لواجهة برمجة التطبيقات أو المَعلمات التي تم ضبطها بنجاح من سطر الأوامر. وقد يفيد ذلك في التأكّد من أنّ علامات سطر الأوامر تعمل على النحو المتوقّع.

في المثال، تم ضبط السمة time_period_per_epoch على 15 ثانية (المدة التلقائية هي سبعة أيام).

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

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 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")

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

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

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