Topics API را پیاده سازی کنید

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

مشاهده و دسترسی به موضوعات

دو راه برای مشاهده و دسترسی به موضوعات یک کاربر وجود دارد: هدرهای HTTP و API جاوا اسکریپت .

هدرهای HTTP

استفاده از هدرهای HTTP یک رویکرد توصیه شده برای مشاهده و دسترسی به موضوعات کاربر است. این رویکرد می‌تواند بسیار کارآمدتر از استفاده از API جاوا اسکریپت باشد. با هدرهای HTTP، URL درخواست، دامنه قابل ثبتی را ارائه می‌دهد که به عنوان دامنه فراخواننده ثبت می‌شود. این دامنه‌ای است که مشاهده می‌شود موضوعات کاربر را مشاهده کرده است.

درخواست را آغاز کنید

دو روش برای استفاده از موضوعات با سربرگ وجود دارد:

• با دسترسی به هدرهای درخواست و پاسخ در یک درخواست fetch() که شامل گزینه browsingTopics: true .
• با دسترسی به هدرهای یک عنصر iframe که شامل ویژگی browsingtopics است.

شروع درخواست با واکشی

با استفاده از fetch، فراخوانی‌کننده‌ی API درخواستی ارسال می‌کند که شامل {browsingTopics: true} در پارامتر options است. مبدا پارامتر URL درخواست fetch، مبدایی است که به نظر می‌رسد موضوعات مشاهده‌شده را دارد.

   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>

تفسیر مقادیر هدر درخواست

برای هر دو رویکرد (fetch و iframe)، موضوعات مشاهده شده برای یک کاربر را می‌توان از هدر درخواست Sec-Browsing-Topics روی سرور بازیابی کرد. API موضوعات، موضوعات کاربر را به طور خودکار در هنگام درخواست fetch() یا iframe در هدر قرار می‌دهد. اگر API یک یا چند موضوع را برگرداند، درخواست fetch به مبدایی که موضوعات از آن مشاهده شده‌اند، شامل یک هدر Sec-Browsing-Topics مانند این خواهد بود:

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

اگر هیچ موضوعی توسط API برگردانده نشود، هدر به این شکل خواهد بود:

   ();p=P0000000000000000000000000000000

تغییر مسیرها دنبال می‌شوند و موضوعات ارسالی در درخواست تغییر مسیر مختص به URL تغییر مسیر خواهند بود. مقادیر سرآیند Sec-Browsing-Topics به صورت padded هستند تا خطر اینکه مهاجم بر اساس طول سرآیند، تعداد موضوعات موجود در محدوده یک فراخوانی‌کننده را متوجه شود، کاهش یابد.

مدیریت پاسخ سمت سرور

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

   res.setHeader('Observe-Browsing-Topics', '?1');

موضوعات مشاهده شده را با شرکا به اشتراک بگذارید

از آنجایی که SSPها فقط در سمت ناشر حضور دارند، DSPها ممکن است بخواهند موضوعاتی را که در سایت‌های تبلیغ‌کننده مشاهده می‌کنند با SSPهای همکار خود به اشتراک بگذارند. آن‌ها می‌توانند این کار را با ارسال یک درخواست fetch() با هدر موضوعات به SSPها از زمینه سطح بالای تبلیغ‌کننده انجام دهند.

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

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

متد document.browsingTopics() از API جاوا اسکریپت مربوط به موضوعات، روشی را برای مشاهده و بازیابی موضوعات مورد علاقه کاربر در محیط مرورگر فراهم می‌کند: - ثبت مشاهده: به مرورگر اطلاع می‌دهد که فراخوانی‌کننده، بازدید کاربر از صفحه فعلی را مشاهده کرده است. این مشاهده به محاسبه موضوع کاربر برای فراخوانی‌کننده در دوره‌های آینده کمک می‌کند. - دسترسی به موضوعات: موضوعاتی را که فراخوانی‌کننده قبلاً برای کاربر مشاهده کرده است، بازیابی می‌کند. این متد آرایه‌ای از حداکثر سه شیء موضوع را برمی‌گرداند، یکی برای هر یک از دوره‌های اخیر، به ترتیب تصادفی.

توصیه می‌کنیم نسخه آزمایشی API جاوا اسکریپت Topics را از اینجا دانلود کنید و از آن به عنوان نقطه شروع کد خود استفاده کنید.

در دسترس بودن API

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

 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 با مبدا متقابل استفاده شود، زیرا زمینه‌ای که API از آن فراخوانی می‌شود برای اطمینان از اینکه مرورگر موضوعات مناسب با فراخوانی‌کننده را برمی‌گرداند، استفاده می‌شود. یک عنصر <iframe> را در HTML خود قرار دهید:

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

همچنین می‌توانید با استفاده از جاوا اسکریپت، یک iframe به صورت پویا ایجاد کنید:

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

فراخوانی API از داخل 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});

درک پاسخ

حداکثر سه موضوع برگردانده می‌شود: یک یا صفر برای هر یک از سه هفته گذشته، بسته به اینکه موضوعات مشاهده شده‌اند یا خیر. فقط موضوعاتی که توسط فراخواننده برای کاربر فعلی مشاهده شده‌اند برگردانده می‌شوند. در اینجا مثالی از آنچه API برمی‌گرداند، آورده شده است:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]

• configVersion : رشته‌ای که نسخه پیکربندی الگوریتم موضوعات مرورگر را مشخص می‌کند.
• modelVersion : رشته‌ای که طبقه‌بندی‌کننده‌ی یادگیری ماشینی مورد استفاده برای استنتاج موضوعات را مشخص می‌کند.
• taxonomyVersion : رشته‌ای که مجموعه موضوعات مورد استفاده مرورگر را مشخص می‌کند.
• موضوع : عددی که موضوع را در طبقه‌بندی مشخص می‌کند.
• version : رشته‌ای که configVersion ، taxonomyVersion و modelVersion را به هم متصل می‌کند. پارامترهای شرح داده شده در این راهنما و جزئیات API (مانند اندازه طبقه‌بندی، تعداد موضوعات محاسبه شده در هفته و تعداد موضوعات برگردانده شده در هر فراخوانی) ممکن است با در نظر گرفتن بازخورد اکوسیستم و تکرار API تغییر کنند.

برای آشنایی با اینکه چه پاسخی را باید انتظار داشت و چگونه می‌توان از موضوعات (Topics) به عنوان یک سیگنال اضافی برای تبلیغات مرتبط‌تر استفاده کرد، به صفحه «آزمایش و پخش زنده» مراجعه کنید.

مراحل بعدی

تست و پخش زنده

نحوه استقرار، آزمایش و مقیاس‌بندی راه‌حل‌های مبتنی بر موضوعات را بیاموزید.

ابزار سازی

درباره ابزارهای موجود در Chrome برای مشاهده اطلاعات Topics API، درک نحوه تخصیص موضوعات و اشکال‌زدایی پیاده‌سازی خود بیاموزید.

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

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

• دموی موضوعات، ویدیوهای مشارکتی و کلیپ را بررسی کنید.
• فهرست پرچم‌های Chrome را ببینید که به توسعه‌دهندگان اجازه می‌دهد تا موضوعات API را برای آزمایش سفارشی کنند.
• ببینید کاربران و توسعه دهندگان چگونه می توانند API را کنترل کنند .
• منابع توضیح دهنده فنی و پشتیبانی را بررسی کنید. سوال بپرسید، مشارکت کنید و بازخورد خود را به اشتراک بگذارید.