راهنمای برنامه‌نویس موضوعات API

با نحوه پیاده سازی Topics API برای مشاهده و دسترسی به موضوع مورد علاقه کاربر با نمونه کد آشنا شوید.

وضعیت پیاده سازی

  • Topics API مرحله بحث عمومی را تکمیل کرده است و در حال حاضر برای 99 درصد از کاربران در دسترس است و تا 100 درصد مقیاس بندی شده است.
  • برای ارائه بازخورد خود در مورد موضوعات API، یک مشکل در توضیح موضوعات ایجاد کنید یا در بحث‌های گروه تجاری بهبود وب تبلیغات شرکت کنید. توضیح دهنده تعدادی سؤال باز دارد که هنوز نیاز به تعریف بیشتری دارد.
  • جدول زمانی Privacy Sandbox جدول زمانی پیاده سازی را برای Topics API و سایر پیشنهادات Privacy Sandbox ارائه می دهد.
  • Topics API: آخرین به‌روزرسانی‌ها جزئیات تغییرات و پیشرفت‌های Topics API و پیاده‌سازی‌ها را نشان می‌دهند.

نسخه ی نمایشی را امتحان کنید

دو نسخه ی نمایشی Topics API وجود دارد که به شما امکان می دهد Topics را به عنوان یک کاربر امتحان کنید.

همچنین می توانید با اجرای Topics colab مدل طبقه بندی کننده Topics را امتحان کنید.

از API جاوا اسکریپت برای دسترسی به موضوعات و ضبط آنها به عنوان مشاهده استفاده کنید

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

پارامترهای توضیح داده شده در این راهنما و جزئیات API (مانند اندازه طبقه بندی، تعداد موضوعات محاسبه شده در هفته و تعداد موضوعات بازگردانده شده در هر تماس) ممکن است با ترکیب بازخورد اکوسیستم و تکرار در API تغییر کنند.

پشتیبانی از document.browsingTopics را شناسایی کنید

قبل از استفاده از API، بررسی کنید که آیا توسط مرورگر پشتیبانی می‌شود و در سند موجود است:

'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');

با جاوا اسکریپت API به موضوعات دسترسی پیدا کنید

در اینجا یک مثال اساسی از استفاده ممکن از 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 API باشد، زیرا API نیاز به ایجاد یک iframe متقاطع و ایجاد یک فراخوان document.browsingTopics() از آن دارد. (یک iframe متقاطع باید برای تماس استفاده شود، زیرا زمینه ای که API از آن فراخوانی می شود برای اطمینان از اینکه مرورگر موضوعات مناسب با تماس گیرنده را برمی گرداند استفاده می شود.) توضیح دهنده Topics بحث بیشتری دارد: آیا راهی برای موضوعات را با استفاده از Fetch به عنوان سرصفحه درخواست ارسال کنید؟ .

از سربرگ Sec-Browsing-Topics یک درخواست fetch() یا XHR می توان به موضوعات دسترسی داشت.

تنظیم یک هدر Observe-Browsing-Topics: ?1 در پاسخ به درخواست باعث می شود که مرورگر بازدید از صفحه فعلی را همانطور که توسط تماس گیرنده مشاهده می شود ثبت کند، بنابراین بعداً می توان از آن در محاسبه موضوعات استفاده کرد.

موضوعات را می توان با هدرهای HTTP به دو صورت مشاهده و مشاهده کرد:

  • fetch() : {browsingTopics: true} را به پارامتر گزینه درخواست fetch() اضافه کنید. نسخه ی نمایشی هدر Topics یک مثال ساده از این را نشان می دهد.
  • ویژگی iframe : ویژگی browsingtopics را به عنصر <iframe> اضافه کنید یا ویژگی جاوا اسکریپت معادل iframe.browsingTopics = true را تنظیم کنید. دامنه قابل ثبت منبع iframe دامنه تماس گیرنده است: به عنوان مثال، برای <iframe src="https://example.com" browsingtopics></iframe> : تماس گیرنده example.com است.

چند نکته اضافی در مورد هدرها:

  • ریدایرکت ها دنبال خواهند شد و موضوعات ارسال شده در درخواست ریدایرکت مختص URL تغییر مسیر خواهد بود.
  • سرصفحه درخواست حالت تماس گیرنده را تغییر نمی دهد مگر اینکه سرصفحه پاسخ مربوطه وجود داشته باشد. یعنی بدون هدر پاسخ، بازدید از صفحه به صورت مشاهده شده ثبت نمی شود، بنابراین بر محاسبه موضوع کاربر برای دوره بعدی تأثیری نخواهد داشت.
  • سرصفحه پاسخ تنها در صورتی مورد احترام قرار می گیرد که درخواست مربوطه شامل سرفصل موضوعات باشد.
  • URL درخواست دامنه قابل ثبت را ارائه می دهد که به عنوان دامنه تماس گیرنده ثبت می شود.

سایت خود را انصراف دهید

شما می توانید با قرار دادن سرصفحه Permissions-Policy: browsing-topics=() Permissions-Policy در یک صفحه از محاسبه موضوع برای صفحات خاصی در سایت خود انصراف دهید تا از محاسبه موضوعات فقط برای همه کاربران در آن صفحه جلوگیری کنید. بازدیدهای بعدی از سایر صفحات سایت شما تحت تأثیر قرار نمی‌گیرد: اگر خط‌مشی برای مسدود کردن Topics API در یک صفحه تنظیم کنید، این روی صفحات دیگر تأثیری نخواهد داشت.

همچنین می توانید با استفاده از هدر Permissions-Policy برای کنترل دسترسی شخص ثالث به Topics API کنترل کنید که کدام شخص ثالث به موضوعات موجود در صفحه شما دسترسی داشته باشد. به عنوان پارامترهای هدر، از self و هر دامنه ای که می خواهید اجازه دسترسی به API را بدهید، استفاده کنید. به عنوان مثال، برای غیرفعال کردن کامل استفاده از Topics API در تمام زمینه‌های مرور به جز مبدا خود و https://example.com ، سرصفحه پاسخ HTTP زیر را تنظیم کنید: 

Permissions-Policy: browsing-topics=(self "https://example.com")

مراحل بعدی

همچنین ببینید

برای درک بهتر Topics API در وب، منابع ما را بررسی کنید.