إعداد 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. تأكَّد من تفعيل جميع واجهات برمجة التطبيقات المتعلّقة بخصوصية الإعلانات ضمن 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 غير مفعّلة تفعيل الإصدار الرابع من إعدادات واجهة مستخدم 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 عدد الفترات الزمنية لبيانات استخدام واجهة برمجة التطبيقات (أي ملاحظات المواضيع) التي سيتم استخدامها لفلترة المواضيع حسب سياق الاتصال
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. جرِّب العروض التوضيحية وشاهِد فيديو الإرشادات حول العروض التوضيحية الخاصة بـ "المواضيع" وColab والأدوات.
    4. يمكنك إنشاء نسخة من العروض التوضيحية وتشغيلها من موقعك الإلكتروني.
    5. يمكنك الاطّلاع على الشرح الخاص بواجهة برمجة التطبيقات لمعرفة المزيد من التفاصيل.
  2. فهم دور واجهة برمجة التطبيقات في تعزيز ملاءمة الإعلانات في المستقبل، حيث لن تتوفّر ملفات تعريف الارتباط التابعة لجهات خارجية لنسبة متزايدة من المستخدمين
  3. لتلقّي إشعارات بشأن تغييرات الحالة في واجهة برمجة التطبيقات، يُرجى الانضمام إلى القائمة البريدية للمطوّرين ومتابعة آخر الأخبار عن Topics API.
  4. يمكنك المساهمة في المحادثة على مشاكل GitHub أو اجتماعات W3C.
  5. إذا صادفت مصطلحات غير مألوفة، راجِع مسرد مصطلحات "مبادرة حماية الخصوصية".
  6. لمزيد من المعلومات حول مفاهيم Chrome، مثل ميزات Chrome التجريبية، راجِع الفيديوهات والمقالات القصيرة المتوفّرة على goo.gle/cc.

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

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