تنفيذ Topics API

توضّح هذه الصفحة تفاصيل التنفيذ التي يجب أن يراعيها مستدعو Topics API عند الوصول إلى المواضيع. قبل البدء في تنفيذ الحلّ، تأكَّد من إعداد المتصفّح بشكل صحيح. راجِع قسم "نظرة عامة" لمعرفة المزيد حول كيفية اطّلاع المتصلين على مواضيع المستخدمين والوصول إليها.

مراقبة المواضيع والوصول إليها

هناك طريقتان لرصد مواضيع المستخدِم والوصول إليها: عناوين HTTP وواجهة برمجة التطبيقات JavaScript.

عناوين HTTP

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

بدء الطلب

تتوفّر طريقتان لاستخدام "المواضيع مع العناوين":

  • من خلال الوصول إلى عناوين الطلبات والاستجابات في طلب fetch() يتضمّن خيار browsingTopics: true
  • من خلال الوصول إلى العناوين لعنصر iframe يتضمّن السمة browsingtopics
بدء الطلب باستخدام عملية جلب

باستخدام fetch، يقدّم طالب البيانات من واجهة برمجة التطبيقات طلبًا يتضمّن {browsingTopics: true} في مَعلمة الخيارات. إنّ مصدر مَعلمة عنوان URL لطلب الجلب هو المصدر الذي تم رصد مواضيع فيه.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
بدء الطلب باستخدام إطار iframe

أضِف السمة browsingtopics إلى العنصر <iframe>. سيتضمّن المتصفّح العنوان Sec-Browsing-Topics في طلب إطار iframe، مع تحديد مصدر إطار iframe على أنّه المتصل.

   <iframe src="https://adtech.example" browsingtopics></iframe>

تفسير قيم عناوين الطلبات

في كلتا الطريقتَين (الجلب وiframe)، يمكن استرداد المواضيع التي تم رصدها للمستخدم على الخادم من عنوان الطلب Sec-Browsing-Topics. ستتضمّن Topics API مواضيع المستخدمين في العنوان تلقائيًا عند طلب fetch() أو طلب إطار iframe. إذا عرضت واجهة برمجة التطبيقات موضوعًا واحدًا أو أكثر، سيتضمّن طلب جلب البيانات إلى المصدر الذي تم رصد المواضيع منه عنوان Sec-Browsing-Topics على النحو التالي:

   (325);v=chrome.1:1:1, ();p=P000000000

إذا لم تعرض واجهة برمجة التطبيقات أي مواضيع، سيبدو العنوان على النحو التالي:

   ();p=P0000000000000000000000000000000

سيتم اتّباع عمليات إعادة التوجيه، وستكون المواضيع المُرسَلة في طلب إعادة التوجيه خاصةً بعنوان URL الخاص بإعادة التوجيه. يتمّ إضافة مساحة فارغة إلى قيم عناوين Sec-Browsing-Topics للحدّ من خطر معرفة عدد المواضيع التي تمّ تحديد نطاقها للمتّصل استنادًا إلى طول العنوان.

التعامل مع استجابة الخادم

إذا تضمّنت الاستجابة للطلب عنوان Observe-Browsing-Topics: ?1، يشير ذلك إلى أنّ المتصفّح يجب أن يضع علامة على المواضيع من الطلب المصاحب باعتبارها مواضيع تمت ملاحظتها، وأن يدرج زيارة الصفحة الحالية في عملية احتساب مواضيع الفترة التالية للمستخدم. أدرِج العنوان Observe-Browsing-Topics: ?1 في الاستجابة في الرمز البرمجي من جهة الخادم:

   res.setHeader('Observe-Browsing-Topics', '?1');
عناوين الطلبات والاستجابات لضبط المواضيع واستردادها
عناوين إطار iframe وfetch()

مشاركة المواضيع التي تم رصدها مع الشركاء

بما أنّ أنظمة وسيط عرض إعلانات المورّدين متوفّرة فقط من جهة الناشر، قد تريد أنظمة وسيط عرض الطلب مشاركة المواضيع التي ترصدها على مواقع المعلِنين مع أنظمة وسيط عرض إعلانات المورّدين الشريكة. ويمكنهم إجراء ذلك من خلال تقديم fetch() طلب يتضمّن عنوان المواضيع إلى منصّات العرض من جهة الخادم من سياق المعلِن ذي المستوى الأعلى.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

مراقبة المواضيع والوصول إليها باستخدام JavaScript

توفّر طريقة Topics JavaScript API ‏document.browsingTopics() وسيلة لمراقبة مواضيع اهتمام المستخدم واستردادها ضمن بيئة المتصفّح: - تسجيل المراقبة: يتم إعلام المتصفّح بأنّ الجهة الطالبة لاحظت أنّ المستخدم يزور الصفحة الحالية. تساهم هذه الملاحظة في احتساب مواضيع المستخدم للمتصل في الفترات المستقبلية. - Access Topics: لاسترداد المواضيع التي رصدها المتصل سابقًا للمستخدم يعرض الإجراء مصفوفة تتضمّن ما يصل إلى ثلاثة عناصر مواضيع، عنصر واحد لكل حقبة من أحدث الحقب، بترتيب عشوائي.

ننصحك بإنشاء نسخة من عرض توضيحي لواجهة برمجة تطبيقات JavaScript الخاصة بميزة "المواضيع" واستخدامها كنقطة بداية لرمزك.

مدى توفّر واجهة برمجة التطبيقات

قبل استخدام واجهة برمجة التطبيقات، تأكَّد من أنّها متوافقة ومتاحة:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

تضمين إطار iframe

يجب استخدام إطار iframe من مصادر متعددة لإجراء الطلب، لأنّ السياق الذي يتم استدعاء واجهة برمجة التطبيقات منه يُستخدَم لضمان أن يعرض المتصفّح المواضيع المناسبة للجهة الطالبة. أدرِج العنصر <iframe> في HTML:

<iframe src="https://example.com" browsingtopics></iframe>

يمكنك أيضًا إنشاء إطار iframe بشكل ديناميكي باستخدام JavaScript:

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

استدعاء واجهة برمجة التطبيقات من داخل إطار iframe

 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() أيضًا إلى تسجيل المتصفّح لزيارة الصفحة الحالية كما يراها المتصل، وبالتالي يمكن استخدامها لاحقًا في احتساب المواضيع. يمكن تمرير وسيطة اختيارية إلى الطريقة لتجنُّب تسجيل زيارة الصفحة: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

فهم الردّ

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

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: سلسلة تحدّد إصدار إعداد خوارزمية "المواضيع" في المتصفّح.
  • modelVersion: سلسلة تحدّد المصنّف المستند إلى تعلُّم الآلة والمستخدَم لاستنتاج المواضيع.
  • taxonomyVersion: سلسلة تحدّد مجموعة المواضيع التي يستخدمها المتصفّح.
  • topic: رقم يعرّف الموضوع في التصنيف.
  • الإصدار: سلسلة تجمع بين configVersion وtaxonomyVersion وmodelVersion. إنّ المَعلمات الموضّحة في هذا الدليل وتفاصيل واجهة برمجة التطبيقات (مثل حجم التصنيف وعدد المواضيع التي يتم احتسابها كل أسبوع وعدد المواضيع التي يتم عرضها في كل طلب) عرضة للتغيير أثناء دمج ملاحظات النظام المتكامل وتكرار واجهة برمجة التطبيقات.

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

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

تعرَّف على كيفية نشر الحلول المستندة إلى المواضيع واختبارها وتوسيع نطاقها.
تعرَّف على الأدوات المتاحة في Chrome لعرض معلومات Topics API وفهم كيفية تخصيص المواضيع وتصحيح أخطاء التنفيذ.

انظر أيضًا

يمكنك الاطّلاع على مراجعنا لفهم Topics API على الويب بشكل أفضل.