إعداد Topics API

جهِّز بيئتك لاستخدام تطبيقات الويب واختبارها وتطويرها باستخدام Topics API.

إنشاء التطبيقات واختبارها محليًا

يوضّح هذا القسم كيفية إعداد بيئتك المحلية لتجربة Topics API بصفتك مطوّرًا فرديًا. ننصحك باستكشاف العروض التوضيحية لفهم آلية عمل Topics قبل البدء في التنفيذ.

تفعيل Topics API في متصفّحك

لتفعيل Topics API في نسخة Chrome الافتراضية الخاصة بك للاختبار المحلي، لديك خياران:

  1. فعِّل جميع واجهات برمجة التطبيقات المتعلّقة بالخصوصية في عرض الإعلانات ضمن chrome://settings/adPrivacy.
  2. (يُنصَح به) يمكنك تشغيل Chrome من سطر الأوامر باستخدام علامات Chromium باستخدام المَعلمات الخاصة بـ Topics API لضبطها حسب الحاجة. يمكنك التحكّم بشكل أدق في ميزات Topics من خلال تشغيل Chrome من سطر الأوامر. على سبيل المثال، من الممكن ضبط فترات Topics (الإطار الزمني الذي تستخدمه واجهة برمجة التطبيقات لاحتساب اهتمامات المستخدمين) وضبط سلوك واجهة برمجة التطبيقات وفقًا لاحتياجاتك.

الاقتراحات الرئيسية

  1. تأكَّد من إغلاق جميع عمليات Chrome وإيقافها قبل بدء العملية الجديدة باستخدام العلامات.
  2. تأكَّد من تفعيل جميع واجهات برمجة التطبيقات Ad Privacy API ضمن "chrome://settings/adPrivacy".
  3. إذا لم تعمل واجهة برمجة التطبيقات على النحو المتوقّع، يمكنك تجربة نصائح تحديد المشاكل وحلّها.
  4. إذا كانت لديك أسئلة، يمكنك الاطّلاع على مشاكل GitHub للاطّلاع على الشرح.

التحكّم في Topics API باستخدام علامات Chrome

يمكن لعلامات 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 مفعّلة تفعيل واجهات برمجة التطبيقات للإعلانات: 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 1000 الحد الأقصى لعدد نطاقات السياق التي يتم تتبّعها حسب أهميتها الغرض من ذلك هو وضع حد أقصى للذاكرة المستخدَمة.
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 إصدار التصنيف الذي تستخدمه واجهة برمجة التطبيقات

قبل البدء في التنفيذ

قبل بدء عملية التنفيذ، ننصحك بمراجعة هذه المراجع للتعرّف على Topics API.

  1. راجِع مستندات المطوّرين:
    1. فهم الغرض من Topics API ودورها في الإعلانات التي تستهدف الاهتمامات
    2. فهم آلية عمل ميزة "مواضيع الإعلانات" على الويب
    3. جرِّب العروض التوضيحية وشاهِد الفيديو التفصيلي عن Topics.
    4. يمكنك إنشاء نسخة من العروض التوضيحية وتشغيلها من موقعك الإلكتروني.
    5. يمكنك الاطّلاع على موضّح لواجهة برمجة التطبيقات للتعرّف على مزيد من التفاصيل.
  2. تعرَّف على دور واجهة برمجة التطبيقات في إتاحة ملفات تعريف الارتباط الخاصة بالإعلانات في المستقبل، حيث لن تتوفّر ملفات تعريف الارتباط التابعة لجهات خارجية لنسبة متزايدة من المستخدمين.
  3. للحصول على إشعارات بشأن تغييرات الحالة في واجهة برمجة التطبيقات، يمكنك الانضمام إلى القائمة البريدية للمطوّرين والاطّلاع على آخر أخبار Topics.
  4. ساهِم في المحادثة حول مشاكل GitHub أو مكالمات W3C.
  5. إذا صادفت عبارات غير مألوفة، راجِع مسرد مصطلحات "مبادرة حماية الخصوصية".
  6. لمزيد من المعلومات حول مفاهيم Chrome، مثل ميزات Chrome الاختبارية، راجِع الفيديوهات والمقالات القصيرة المتوفّرة على goo.gle/cc.

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

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