تنظیمات API موضوعات

با Topics API محیط خود را برای استفاده، آزمایش و توسعه برنامه های وب آماده کنید.

به صورت محلی بسازید و آزمایش کنید

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

موضوعات را در مرورگر خود فعال کنید

برای فعال کردن Topics API در نمونه کروم خود برای آزمایش محلی، دو گزینه دارید:

  1. همه APIهای حریم خصوصی تبلیغات را در chrome://settings/adPrivacy فعال کنید.
  2. (توصیه می شود) Chrome را از خط فرمان با پرچم های Chromium با استفاده از پارامترهای خاص Topics API اجرا کنید تا در صورت نیاز پیکربندی شود. با اجرای Chrome از خط فرمان، کنترل دقیق تری بر ویژگی های Topics دارید. برای مثال، می‌توانید دوره‌های Topics (بازه زمانی مورد استفاده توسط API برای محاسبه علایق کاربر) را تنظیم کنید و رفتار API را بر اساس نیازهای خود پیکربندی کنید.

توصیه های کلیدی

  1. اطمینان حاصل کنید که قبل از شروع فرآیند جدید با استفاده از پرچم‌ها، تمام فرآیندهای Chrome را ببندید و متوقف کنید.
  2. مطمئن شوید که همه APIهای حریم خصوصی تبلیغات در chrome://settings/adPrivacy فعال هستند.
  3. اگر API همانطور که انتظار می رود کار نمی کند، نکات عیب یابی ما را امتحان کنید.
  4. اگر سؤالی دارید، مشکلات GitHub را برای توضیح دهنده بررسی کنید.

API موضوعات را با پرچم کروم کنترل کنید

پرچم‌های Chrome می‌توانند رفتار Topics API را تغییر دهند. Chrome را از خط فرمان با پارامترهای مشخص شده برای تسهیل تست اجرا کنید. به عنوان مثال، نسخه ی نمایشی هدر استفاده از پرچم های زیر را توصیه می کند:

--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting

جدول زیر هر پارامتر، مقدار پیش فرض و هدف آن را توضیح می دهد.

نام پرچم مقدار پیش فرض توضیحات
BrowsingTopics فعال شد اینکه آیا Topics API فعال است یا خیر.
PrivacySandboxAdsAPIsOverride فعال شد APIهای تبلیغاتی را فعال می کند: گزارش اسناد، مخاطبین محافظت شده، موضوعات، قاب های حصاردار.
PrivacySandboxSettings4 از کار افتاده است چهارمین نسخه تنظیمات رابط کاربری Privacy Sandbox را فعال می کند.
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 چند دوره از داده‌های استفاده از API (یعنی مشاهدات موضوعات) برای فیلتر کردن موضوعات برای یک زمینه فراخوانی استفاده خواهد شد.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic 1000 حداکثر تعداد دامنه‌های زمینه مشاهده شده برای هر موضوع برتر. هدف این است که حافظه در حال استفاده را محدود کنیم.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch 100000 حداکثر تعداد ورودی های مجاز برای بازیابی از پایگاه داده برای هر پرس و جو برای زمینه های استفاده API. پرس و جو یک بار در هر دوره در زمان محاسبه موضوعات رخ می دهد. هدف این است که حداکثر استفاده از حافظه را محدود کنیم.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load 30 حداکثر تعداد دامنه های زمینه استفاده از API مجاز به ذخیره در هر بارگذاری صفحه.
BrowsingTopics:config_version 1 پارامترهای پیکربندی Topics API را رمزگذاری می کند. هر شماره نسخه فقط باید به یک مجموعه پیکربندی نگاشت شود. به‌روزرسانی پارامترهای پیکربندی بدون به‌روزرسانی config_version معمولاً برای آزمایش محلی مناسب است، اما در برخی شرایط می‌تواند مرورگر را در وضعیت ناسازگاری قرار دهد و منجر به خرابی مرورگر شود، برای مثال به‌روزرسانی number_of_top_topics_per_epoch .
BrowsingTopics:taxonomy_version 1 نسخه طبقه بندی مورد استفاده توسط API.

قبل از شروع پیاده سازی

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

  1. بررسی اسناد توسعه دهنده:
    1. هدف Topics API و نقش آن در تبلیغات مبتنی بر علاقه را درک کنید
    2. نحوه عملکرد Topics در وب را درک کنید.
    3. نسخه‌های نمایشی را امتحان کنید و ویدیوی دموی موضوعات، همکاری و ابزارها را تماشا کنید.
    4. دموها را فورک کنید و از سایت خودتان اجرا کنید.
    5. برای درک بیشتر جزئیات، توضیح API را بخوانید.
  2. نقش API را در حمایت از ارتباط تبلیغات در آینده، جایی که کوکی‌های شخص ثالث برای تعداد فزاینده‌ای از کاربران در دسترس نخواهد بود، درک کنید.
  3. برای اطلاع از تغییرات وضعیت در API، به لیست پستی توسعه دهندگان بپیوندید و منتظر آخرین به روز رسانی موضوعات باشید.
  4. در گفتگو در مورد مسائل GitHub یا تماس های W3C مشارکت کنید.
  5. اگر با اصطلاحات ناآشنا مواجه شدید، واژه نامه Privacy Sandbox را مرور کنید.
  6. برای اطلاعات بیشتر درباره مفاهیم Chrome، مانند پرچم‌های Chrome، ویدیوها و مقالات کوتاه موجود در goo.gle/cc را مرور کنید.

مراحل بعدی

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