دليل مطوّري واجهة برمجة التطبيقات Protected Audience API

أثناء قراءة مستندات "مبادرة حماية الخصوصية" على Android، استخدِم الزر الإصدار التجريبي للمطوّرين أو الإصدار التجريبي لاختيار إصدار البرنامج الذي تستخدمه، لأنّ التعليمات قد تختلف.

تتضمّن Protected Audience API على Android (المعروفة سابقًا باسم FLEDGE) Custom Audience API وAd Selection API. يمكن لمنصّات تقنية الإعلان والمعلِنين استخدام واجهات برمجة التطبيقات هذه لعرض إعلانات مخصّصة استنادًا إلى التفاعلات السابقة مع التطبيقات التي تحدّ من مشاركة المعرّفات على مستوى التطبيقات، كما تحدّ من مشاركة معلومات تفاعل المستخدِم مع التطبيقات مع جهات خارجية.

تركّز Custom Audience API على العنصر المجمّع "شريحة الجمهور المخصّصة"، الذي يمثّل مجموعة من المستخدِمين الذين لديهم نيّات مشتركة. يمكن للمعلِن تسجيل مستخدم في شريحة جمهور مخصّصة وربط الإعلانات ذات الصلة بها. يتم تخزين هذه المعلومات على الجهاز، ويمكن استخدامها لإعلام المعلِن بعروض الأسعار وفلترة الإعلانات وعرضها.

توفّر واجهة برمجة التطبيقات Ad Selection API إطار عمل يسمح لمطوّرين متعدّدين ب إجراء مزاد محلي لشريحة جمهور مخصّصة. ولتحقيق ذلك، يأخذ النظام في الاعتبار الإعلانات ذات الصلة المرتبطة بالجمهور المخصّص ويُجري معالجة إضافية للإعلانات التي تعرضها منصة تكنولوجيا الإعلان على الجهاز.

يمكن لمنصّات تكنولوجيا الإعلان دمج واجهات برمجة التطبيقات هذه لتنفيذ تجديد النشاط التسويقي الذي يحافظ على خصوصية المستخدِم. من المخطّط أن تتوفّر حالات استخدام إضافية في الإصدارات المستقبلية، بما في ذلك إعلانات تثبيت التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول واجهة برمجة التطبيقات Protected Audience API على Android في اقتراح التصميم.

يوضّح هذا الدليل كيفية استخدام Protected Audience API على Android للقيام بما يلي:

1. إدارة شرائح الجمهور المخصّصة
2. إعداد ميزة "اختيار الإعلانات" وتشغيلها على جهاز
3. الإبلاغ عن مرّات ظهور الإعلانات

قبل البدء

قبل البدء، يُرجى إكمال ما يلي:

1. إعداد بيئة التطوير لـ "مبادرة حماية الخصوصية" على Android
2. عليك تثبيت صورة نظام على جهاز متوافق أو إعداد UMEMULATOR يتيح استخدام "مبادرة حماية الخصوصية" على Android.

3. في وحدة طرفية، فعِّل الوصول إلى Protected Audience API (متوقفة تلقائيًا) باستخدام الأمر adb التالي.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. في وحدة طرفية، فعِّل الإبلاغ عن الإشارات باستخدام أوامر adb التالية.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. يجب تضمين إذن ACCESS_ADSERVICES_CUSTOM_AUDIENCE في بيان تطبيقك:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

6. يمكنك الإشارة إلى إعدادات خدمات الإعلانات في عنصر <application> ضمن بيانك:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. حدِّد مرجع XML لخدمات الإعلانات المُشار إليه في البيان، مثل res/xml/ad_services_config.xml. مزيد من المعلومات حول أذونات خدمات الإعلانات وإمكانية التحكّم في الوصول إلى حِزم تطوير البرامج (SDK)

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. تفرض Ad Selection API تلقائيًا حدودًا على الحد الأقصى للمساحة المتوفّرة في الذاكرة التي يمكن أن تخصصها برمجة ملف تعريف الارتباط لإعداد تقارير المزاد أو مرّات الظهور. تتطلّب ميزة الحدّ من استخدام الذاكرة استخدام الإصدار 105.0.5195.58 من WebView أو إصدار أحدث. تفرض المنصة فحصًا للإصدار، وتتعذّر طلبات البيانات من واجهتَي برمجة التطبيقات selectAds وreportImpression في حال عدم استيفاء هذا الفحص. هناك خياران لإعداد هذا الإجراء:

   • الخيار 1: يمكنك تشغيل الأمر adb التالي لإيقاف هذا التحقّق:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • الخيار 2: تثبيت WebView Beta من متجر Google Play يجب أن يكون هذا الإصدار مساويًا للإصدار المذكور سابقًا أو أعلى منه.

الانضمام إلى شريحة جمهور مخصّصة

تمثّل شريحة الجمهور المخصّصة مجموعة من المستخدِمين الذين لديهم نوايا أو اهتمامات مشتركة وفقًا لما يقرّره تطبيق المعلِن. ويمكن أن يستخدم التطبيق أو حزمة تطوير البرامج (SDK) شريحة جمهور مخصّصة للإشارة إلى شريحة جمهور معيّنة، مثل المستخدِم الذي ترك سلعًا في سلة تسوّق. لإنشاء شريحة جمهور مخصّصة أو الانضمام إليها بشكل غير متزامن، اتّبِع الخطوات التالية:

1. اضبط العنصر CustomAudienceManager على القيمة الأولية.
2. أنشئ عنصر CustomAudience من خلال تحديد مَعلمات رئيسية، مثل حزمة المشتري واسم ذي صلة. بعد ذلك، يمكنك إعداد كائن JoinCustomAudienceRequest باستخدام كائن CustomAudience.
3. استخدِم الإجراء غير المتزامن joinCustomAudience() مع العنصر JoinCustomAudienceRequest والعنصرَين Executor و OutcomeReceiver ذات الصلة.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

تُحدِّد مجموعة المَعلمات التالية بشكلٍ فريد كل كائن CustomAudience على جهاز:

• ‫owner: اسم حزمة التطبيق مالك المحتوى. يتم ضبط هذا العنصر بشكل ضمني على اسم حزمة التطبيق المُرسِل.
• buyer: معرّف لشبكة إعلانات المشترين التي تدير الإعلانات لهذا الجمهور المخصّص.
• name: اسم أو معرّف عشوائي للجمهور المخصّص.

يؤدي استدعاء joinCustomAudience() بشكل متكرّر باستخدام مثيل مختلف من CustomAudience إلى تعديل أيّ CustomAudience حالية باستخدام مَعلمتَي owner, buyer وname المطابقتَين. للمساعدة في الحفاظ على الخصوصية، لا تميّز نتيجة واجهة برمجة التطبيقات بين "الإنشاء" و "التعديل".

بالإضافة إلى ذلك، يجب إنشاء CustomAudience باستخدام المَعلمات التالية المطلوبة:

• عنوان URL للتعديل اليومي: عنوان URL لبروتوكول HTTPS يتم الاستعلام عنه يوميًا في الخلفية لتعديل إشارات عروض أسعار المستخدِمين في شريحة الجمهور المخصّصة وبيانات عروض الأسعار الموثوق بها، وعرض عناوين URL والبيانات الوصفية للإعلانات.
• عنوان URL لمنطق عروض الأسعار: عنوان URL يستخدم HTTPS يتم الاستعلام عنه أثناء اختيار الإعلان لجلب ملف JavaScript الخاص بمنطق عروض أسعار المشتري. اطّلِع على نماذج الدوالّ المطلوبة في JavaScript.
• معرّفات عرض الإعلانات: معرّف عشوائي تحدّده تكنولوجيا إعلانات المشترين. وهذا تحسين لإنشاء الحمولة لميزة B&A.

قد تتضمّن المَعلمات الاختيارية لكائن CustomAudience ما يلي:

• وقت التفعيل: لا يمكن لشريحة جمهور مخصّصة المشاركة في اختيار الإعلانات والتعديلات اليومية إلا بعد وقت التفعيل. ويمكن أن يكون ذلك مفيدًا للتفاعل مع المستخدمين الذين توقّفوا عن استخدام أحد التطبيقات، على سبيل المثال.
• وقت انتهاء الصلاحية: وقت مستقبلي تتم بعده إزالة شريحة الجمهور المخصّصة من الجهاز.
• إشارات عروض أسعار المستخدِم: سلسلة JSON تحتوي على إشارات المستخدِم، مثل اللغة المفضّلة للمستخدِم، التي يستخدِمها JavaScript الخاص بمنطق عروض أسعار المشترِي لإنشاء عروض الأسعار أثناء عملية اختيار الإعلان. يساعد هذا التنسيق منصّات تكنولوجيا الإعلان في إعادة استخدام الرموز البرمجية على جميع المنصّات وتسهيل استخدام دوال JavaScript.
• بيانات عروض الأسعار الموثوق بها: عنوان URL لبروتوكول HTTPS وقائمة بالسلاسل المستخدَمة أثناء عملية اختيار الإعلانات التي تُستخدَم لجلب إشارات عروض الأسعار من خدمة موثوق بها لمعالجة السلاسل المفتاح/القيمة
• الإعلانات: قائمة بعناصر AdData التي تتوافق مع الإعلانات التي تشارك في اختيار الإعلانات يتألّف كل عنصر AdData من:
  • عنوان URL لعرض الإعلان: عنوان URL يستخدم HTTPS يتمّ الاستعلام عنه لعرض الإعلان النهائي.
  • البيانات الوصفية: عنصر JSON مُسلسل كسلسلة تحتوي على معلومات لاستخدامها في منطق عروض أسعار المشترين أثناء عملية اختيار الإعلان.
  • فلاتر الإعلانات: فئة تحتوي على كل المعلومات اللازمة لتطبيق فلترة الإعلانات والحدّ الأقصى لعدد مرّات الظهور أثناء اختيار الإعلان.

في ما يلي مثال على إنشاء مثيل لعنصر CustomAudience:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

التعامل مع نتائج joinCustomAudience()

تستخدِم طريقة joinCustomAudience() غير المتزامنة العنصر OutcomeReceiver للإشارة إلى نتيجة طلب البيانات من واجهة برمجة التطبيقات.

• يشير ردّ الاتصال onResult() إلى أنّه تم بنجاح إنشاء شريحة الجمهور المخصّصة أو تعديلها.
• يشير طلب إعادة الاتصال onError() إلى حالتَين محتملتَين.
  • إذا تمّت بدء JoinCustomAudienceRequest باستخدام دلايلات غير صالحة، يشير AdServicesException إلى IllegalArgumentException كسبب.
  • تتلقّى جميع الأخطاء الأخرى رمز AdServicesException مع رمز IllegalStateException كسبب.

في ما يلي مثال على معالجة نتيجة joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

مغادرة شريحة جمهور مخصّصة

إذا لم يعُد المستخدم يستوفي معايير النشاط التجاري لشريحة محددة من الجمهور المخصّص، يمكن للتطبيق أو حزمة تطوير البرامج (SDK) الاتصال بـ leaveCustomAudience() لإزالة شريحة الجمهور المخصّصة من الجهاز. لإزالة CustomAudience استنادًا إلى مَعلماته الفريدة، اتّبِع الخطوات التالية:

1. اضبط العنصر CustomAudienceManager على القيمة الأولية.
2. اضبط متغيّر LeaveCustomAudienceRequest باستخدام buyer وname لشريحة الجمهور المخصّصة. للاطّلاع على مزيد من المعلومات عن حقول الإدخال هذه، يمكنك قراءة مقالة الانضمام إلى شريحة جمهور مخصّصة.
3. استدِع الطريقة غير المتزامنة leaveCustomAudience() باستخدام كائن LeaveCustomAudienceRequest وكائنَي Executor و OutcomeReceiver ذات الصلة.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

على غرار استدعاء joinCustomAudience()، يشير الرمز OutcomeReceiver إلى نهاية طلب بيانات من واجهة برمجة التطبيقات. للمساعدة في حماية الخصوصية، لا يصنّف نتيجة الخطأ بين الأخطاء الداخلية والوسيطات غير الصالحة. يتمّ استدعاء onResult() دالة الاستدعاء عند اكتمال طلب البيانات من واجهة برمجة التطبيقات، سواء تمّت إزالة قاعدة جماهيرية مخصّصة مطابقة بنجاح أم لا.

تنفيذ اختيار الإعلان

لاستخدام Protected Audience API لاختيار الإعلانات، يمكنك استدعاء الطريقة selectAds():

1. شغِّل عنصر AdSelectionManager.
2. أنشئ عنصر AdSelectionConfig.
3. استدِع الطريقة غير المتزامنة selectAds() باستخدام كائن AdSelectionConfig وكائنَي Executor و OutcomeReceiver ذات الصلة.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

تتطلّب طريقة selectAds() إدخال AdSelectionConfig، حيث يجب تحديد المَعلمات المطلوبة التالية:

• البائع: معرّف لشبكة إعلانات البائع التي تبدأ عملية اختيار الإعلان.
• عنوان URL لمنطق القرار: عنوان URL يستخدم HTTPS يتمّ الاستعلام عنه للحصول على منطق JavaScript لشبكة الإعلانات الخاصة بالبائع.
  • عنوان URL يستخدم HTTPS: يتمّ الاستعلام عنه للحصول على منطق JavaScript لشبكة الإعلانات الخاصة بالبائع. اطّلِع على نماذج الدوالّ المطلوبة.
  • معرّف URI مُنشأ مسبقًا: يتبع تنسيق اختيار الإعلانات في FLEDGE. يتم طرح IllegalArgumentException إذا تم تمرير معرّف موارد منتظم (URI) prebuilt غير متوافق أو غير صحيح.
• شراة شرائح الجمهور المخصّصة: قائمة كاملة بالمعرّفات لشبكات الإعلانات الخاصة بالمشترين التي يسمح لها البائع بالمشاركة في عملية اختيار الإعلانات. تتطابق معرّفات المشترين هذه مع CustomAudience.getBuyer() من شرائح الجمهور المخصّصة المشارِكة.

يمكن تحديد المَعلمات التالية اختياريًا لاختيار إعلانات أكثر تخصيصًا:

• إشارات اختيار الإعلانات: كائن JSON، يتم تسلسله كسلسلة، يحتوي على إشارات يتم استخدامها من خلال JavaScript الخاص بمنطق عروض أسعار المشترين ويتم جلبها من CustomAudience.getBiddingLogicUrl().
• إشارات البائع: كائن JSON مُسلسل كسلسلة يحتوي على إشارات يستخدمها منطق اتخاذ القرار المستند إلى JavaScript الذي جلبه البائع من AdSelectionConfig.getDecisionLogicUrl().
• إشارات لكلّ مشترٍ: فهرس لكائنات JSON، يتم تسلسلها كسلسلة، يحتوي على إشارات يتم استخدامها من خلال JavaScript الخاص بمنطق عروض أسعار مشترين محدّدين يتم جلبها من CustomAudience.getBiddingLogicUrl()، ويتم تحديدها من خلال حقول المشترين للشرائح المخصّصة المشارِكة.
• الإعلانات السياقية: مجموعة من الإعلانات المُحتمَلة التي يتم جمعها مباشرةً من المشترين خلال مزاد يتم خارج مزاد "شريحة الجمهور المحمية" .

بعد اختيار إعلان، يتم الاحتفاظ بالنتائج وعروض الأسعار والإشارات داخليًا لإعداد التقارير. تُعرِض دالة ردّ الاتصال OutcomeReceiver.onResult() AdSelectionOutcome يحتوي على ما يلي:

• عنوان URL لعرض الإعلان الفائز، تم الحصول عليه من AdData.getRenderUrl()
• معرّف اختيار إعلان فريد لمستخدِم الجهاز يُستخدَم هذا المعرّف لإعداد تقارير عن أثر إعلان معيّن.

إذا تعذّر إكمال اختيار الإعلان بنجاح للأسباب التالية، مثلاً: المَعلمات غير الصالحة أو وقت الاستراحة أو استهلاك الموارد بشكل مفرط، يقدّم الإجراء المرجعي OutcomeReceiver.onError() AdServicesException بالسلوكيات التالية:

• إذا تم بدء اختيار الإعلان باستخدام وسيطات غير صالحة، يشير الرمز AdServicesException إلى IllegalArgumentException كسبب.
• تتلقّى جميع الأخطاء الأخرى رمز AdServicesException مع رمز IllegalStateException كسبب.

الإعلانات السياقية

يمكن أن تدمج واجهة برمجة التطبيقات Protected Audience الإعلانات السياقية في مزاد محمي. يجب اختيار الإعلانات السياقية على خادم تكنولوجيا الإعلان وإعادتها إلى الجهاز خارج واجهات برمجة التطبيقات Protected Audience API. يمكن بعد ذلك تضمين الإعلانات السياقية في المزاد باستخدام AdSelectionConfig، وعند هذه النقطة تعمل الإعلانات بالطريقة نفسها التي تعمل بها الإعلانات على الجهاز، بما في ذلك الأهلية لفلترة الإعلانات السلبية. بعد اكتمال مزاد "الجمهور المحمي"، عليك استدعاء reportImpression(). يؤدي ذلك إلى استدعاء reportWin() في الإعلان السياقي الفائز، بالطريقة نفسها المستخدَمة في إعداد تقارير مرّات الظهور، لتلقّي الإعلان الفائز على أحد الأجهزة. يحتاج كل إعلان سياقي إلى مشتري وعرض سعر ورابط إلى منطق إعداد التقارير و عنوان URL لعرض الإعلان وبيانات وصفية للإعلان.

لنشر الإعلانات السياقية داخل التطبيق، يجب أن ينشئ التطبيق المستهدَف عنصرًا ContextualAds:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

يمكن بعد ذلك تمرير عنصر ContextualAds الناتج عند إنشاء AdSelectionConfig:

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

فلترة إعلانات تثبيت التطبيقات

تساعدك ميزة فلترة إعلانات تثبيت التطبيقات على فلترة إعلانات التثبيت للتطبيقات التي سبق تثبيتها على أحد الأجهزة.

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

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

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

الخطوة التالية هي إعداد فلترة الإعلانات داخل تطبيق الناشر. على الطرف الذي يعرض الإعلان داخل تطبيق الناشر (من المرجّح أن يكون حزمة تطوير برامج (SDK) من جهة العرض) بدء عنصر AdFilters الذي يتضمن معلومات عن الإعلانات التي يريد فلترتها والتي تتعلّق بالتطبيقات:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

يمكن للناشرين على جانب الطلب أيضًا ضبط AdFilter للإعلانات المتوفّرة داخل شرائح جمهورهم المخصّصة.

يمكن أيضًا تمرير AdFilters عند إنشاء AdData كائن جديد:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

فلترة تحديد عدد مرّات الظهور

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

هناك مكوّنان رئيسيان لفلترة الحدّ الأقصى لعدد مرّات الظهور: نوع حدث الإعلان، ومفتاح عدّاد الإعلانات. في ما يلي أنواع أحداث الإعلانات المتاحة التي يمكن استخدامها:

• الفوز: يشير حدث الفوز إلى أنّ الإعلان فاز بمزاد. تعمل Protected Audience API على تعديل أحداث الفوز تلقائيًا ولا يمكن للمطوّر استدعاؤها مباشرةً. لا تظهر بيانات الفوز إلا للإعلانات ضمن قاعدة جماهيرية مخصّصة معيّنة.
• مرّة الظهور: على عكس reportImpression، يستخدم المُرسِل على الجهاز (SSP أو MMP) updateAdCounterHistogram() لتشغيل أحداث مرّات الظهور في النقطة التي يختارها في الرمز. تظهر أحداث مرّات الظهور لجميع الإعلانات التي تنتمي إلى نظام وسيط عرض طلب معيّن، ولا تقتصر على الإعلانات في شريحة الجمهور المخصّصة نفسها.
• عرض: يستدعي المُتصل على الجهاز (SSP أو MMP) الحدث في نقطة في الرمز البرمجي يختارها باستخدام طلب إلى updateAdCounterHistogram(). تكون أحداث المشاهدة مرئية لجميع الإعلانات التي تنتمي إلى نظام وسيط عرض طلب معيّن، ولا تقتصر على الإعلانات في شريحة الجمهور المخصّصة نفسها.
• النقرة: يستدعي المُرسِل على الجهاز (SSP أو MMP) الحدث في نقطة في الرمز البرمجي يختارها باستخدام طلب إلى updateAdCounterHistogram(). إنّ أحداث النقر تكون مرئية لجميع الإعلانات التي تنتمي إلى نظام وسيط عرض طلب معيّن، ولا تقتصر على الإعلانات في شريحة الجمهور المخصّصة نفسها.

في تطبيق الناشر، يُنشئ منصّة SSP أو منصّة إدارة الأداء التسويقي (MMP) التي تتوفّر على الجهاز أحداث إعلانات. عند استدعاء updateAdCounterHistogram()، يتمّ زيادة مُحتسِب فلتر تحديد عدد مرات الظهور، وذلك لكي تتضمّن المزادات المستقبلية معلومات محدّثة عن مدى رؤية المستخدِم لإعلان معيّن. لا يتم ربط أنواع أحداث الإعلانات بشكلٍ إجباري بإجراء المستخدِم المقابل، وهي إرشادات يتم تقديمها لمساعدة المُرسِلين في تنظيم نظام الأحداث. لزيادة عدادات الإعلانات في وقت حدث معيّن، يقدّم العنصر المشغّل على الجهاز رقم تعريف اختيار الإعلان في مزاد الإعلانات الفائز.

مفاتيح عدّ الظهور للإعلانات هي أعداد صحيحة موقَّعة عشوائية بسعة 32 بت تحدّدها تكنولوجيا الإعلان للمشتري، وهي تتوافق مع مجموعة معيّنة من الإعلانات كما تحدّدها منصّة إدارة الأداء (DSP). بما أنّ مفاتيح عداد الإعلانات محدودة بالإعلانات التي تنتمي إلى منصّة إدارة إعلانات معيّنة، يمكن اختيار هذه المفاتيح بدون تداخل مع الرسوم البيانية من تقنية إعلان أخرى. وتُستخدَم مفاتيح عداد الإعلانات لزيادة المعرّفات الخاصة بمنصّة إدارة الإعلانات على مستوى إعلانات منصّة إدارة الإعلانات أو ضمن شريحة جمهور مخصّصة معيّنة لفلترة الإعلانات من المزادات المستقبلية.

يمكن الاستفادة من مفاتيح العدّ لتخصيص الأولوية للإعلانات التي يُرجّح أن تكون مثيرة للاهتمام لمستخدم معيّن استنادًا إلى تفاعلاته مع إعلانات أخرى من تكنولوجيا إعلانية معيّنة للمشتري. على سبيل المثال، يمثّل الإعلان الذي تلقّى مستوى مرتفعًا من التفاعل من خلال المزادات الإعلانية الفائزة والمشاهدات والنقرات نقطة بيانات مستنتَجة. لتوضيح هذه النقطة بشكل أكبر، قد يشير إعلان عن مضارب غولف مناسبة للّاعبين الأيمنين إلى أنّ المستخدم لن يكون مهتمًا بالمضارب المناسبة للّاعبين الأيسرين. يمكن أن يؤدي استخدام فلتر تحديد عدد مرّات الظهور الذي تم ضبطه لمفتاح عدّ تمّ تعيينه للإعلانات المخصّصة للّاعبين الأيمنين إلى استبعاد الإعلانات المخصّصة للّاعبين الأيسرين.

لاستخدام ميزة تحديد عدد مرّات الظهور في المزاد، عليك أولاً إنشاء KeyedFrequencyCap عنصرَين:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

بعد إنشاء عناصر KeyedFrequencyCap، يمكنك تمريرها إلى عنصر AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

عند تعبئة عنصر AdFilters بفلاتر تحديد عدد مرّات الظهور، يمكن تمريره عند إنشاء شريحة الجمهور المخصّصة:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

عند تنفيذ فلاتر الحدّ الأقصى لمعدّل التكرار في شريحة جمهور مخصّصة، يمكن لوحدة إدارة المساحة الإعلانية بعد ذلك استدعاء أحداث النقرات أو المشاهدات أو مرّات الظهور اللازمة.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

يتم استبعاد الإعلانات التي بلغت حدود فلتر تحديد عدد مرّات الظهور المحدّدة مسبقًا من المزاد. يتمّ الفلترة قبل تنفيذ منطق عروض الأسعار لأجل المزادات على الجهاز، وبينما يتمّ إنشاء الحمولة لأجل مزادات خدمات عروض الأسعار والمزادات.وتمنح هذه المجموعة من الأدوات تكنولوجيات الإعلان المرونة في استخدام التفاعلات بين المستخدِمين والإعلانات ضمن شرائح الجمهور المخصّصة لتركيز استهداف الإعلانات مع الحدّ من التعرض المفرط للإعلانات.

فلترة الإعلانات السياقية بدون طلبات بيانات من الشبكة

إذا لم يكن هناك طلب تجديد نشاط تسويقي على الجهاز، يمكنك تنفيذ اختيار الإعلانات لأجل الإعلانات السياقية بدون طلبات بيانات من الشبكة. باستخدام عناوين URL مُنشأة مسبقًا وقائمة بالإعلانات المعروضة على السياق التي تتضمّن عروض أسعار، يمكن للنظام الأساسي تخطّي استرداد منطق عروض الأسعار وإشارات عروض الأسعار وإشارات التقييم. تستخدِم المنصة عنوان URL مُعدّ مسبقًا لاختيار الإعلان السياقي الذي يضمّ أعلى عرض سعر.

لتحسين وقت الاستجابة، يمكن لتكنولوجيات الإعلان تنفيذ عملية اختيار إعلانات تتضمّن فقط الإعلانات السياقية مع وظيفة فلترة الإعلانات بدون طلبات بيانات من الشبكة. ويتمّ تحقيق ذلك باستخدام معرّفات الموارد المنتظمة (URI) المُنشأة مسبقًا لتحديد علامات الأداء. يُرجى الرجوع إلى قسم حالات الاستخدام والأسماء المتوافقة لعناوين URL المُنشأة مسبقًا للحصول على قائمة بعمليات scoreAds التنفيذ.

لتنفيذ اختيار الإعلانات بدون إجراء مكالمات إلى الشبكة:

1. إعداد فلترة الإعلانات
2. إنشاء إعلاناتك السياقية

3. أنشئ عنصر AdSelectionConfig باستخدام ما يلي:

   1. قائمة فارغة بالمشترين
   2. عنوان URL مُنشأ مسبقًا لاختيار أعلى عرض سعر
   3. الإعلانات السياقية
   4. معرّف موارد منتظم فارغ لإشارات التقييم يُسمح باستخدام معرّف الموارد المنتظم الفارغ للإشارة إلى أنّك لا تريد استخدام جلب الإشارات الموثوق بها لتحديد النقاط:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. تنفيذ اختيار الإعلان:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

تشغيل JavaScript الخاص بإعداد التقارير أثناء استخدام عناوين URL مُنشأة مسبقًا

في الوقت الحالي، تتضمّن منصة "مبادرة حماية الخصوصية" تنفيذًا أساسيًا لإعداد التقارير باستخدام JavaScript ، وهو متاح فقط لعناوين URL المُنشأة مسبقًا. إذا كنت تريد تشغيل ملف JavaScript الخاص بك لإعداد التقارير مع الاستمرار في استخدام عناوين URL مُنشأة مسبقًا لاختيار إعلانات يتسم وقت استجابةه بالانخفاض، يمكنك إلغاء DecisionLogicUri بين اختيار الإعلانات وعمليات إعداد التقارير.

1. اتّبِع الخطوات لتشغيل ميزة اختيار الإعلانات للإعلانات السياقية باستخدام معرّفات الموارد المنتظمة (URI) المُنشأة مسبقًا.

2. أنشئ نسخة من AdSelectionConfig قبل إعداد التقارير.

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. تشغيل تقارير مرّات الظهور

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

تشغيل توسّط العرض الإعلاني بدون انقطاع

يتطلّب التوسّط الإعلاني بدون انقطاع حِزم تطوير برامج (SDK) متعددة تابعة لجهات خارجية (شبكات تابعة لجهات خارجية) ليتم تنسيقها من خلال شبكة توسّط حِزم تطوير برامج (SDK) تابعة لجهة أولى. تتمّ معالجة الإعلانات المعروضة بدون انقطاع بالطريقة نفسها بغض النظر عمّا إذا كان المزاد قد تمّ على الجهاز أو تمّ تنفيذه على خدمات عروض الأسعار والمزادات (B&A).

شبكات الجهات الخارجية

يجب أن توفّر شبكات الجهات الخارجية محوِّلًا يسمح لشبكة التوسّط باستدعاء الطرق اللازمة لإجراء مزاد:

• تنفيذ اختيار الإعلان
• عدد مرّات ظهور التقرير

في ما يلي مثال على محوِّل شبكة التوسّط:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

لكلّ حزمة تطوير برامج (SDK) مدراء وعملاء خدمة اختيار الإعلانات، وعمليات تنفيذ selectAds وreportImpressions خاصة بها. يمكن لموفّري حِزم تطوير البرامج (SDK) الرجوع إلى الأقسام حول كيفية تنفيذ اختيار الإعلان للمزادات على الجهاز أو الاطّلاع على الشرح المتعلّق بالمزادات التي تشمل عروض"الإعلانات المتجاوبة على شبكة البحث". اتّبِع خطوات إعداد تقارير عن مرّات ظهور الإعلانات (اتّباع إعداد تقارير مرّات ظهور إعلانات في منصّة SSP واحدة لإعداد تقارير الأداء).

شبكة التوسّط

على غرار الشبكات التابعة لجهات خارجية، تحتاج شبكات التوسّط إلى عمليات تنفيذ selectAds و reportImpression. يُرجى الرجوع إلى الأقسام حول كيفية تنفيذ ميزة "تصعيد الإعلان" وكيفية إعداد تقارير مرّات ظهور الإعلان للحصول على مزيد من المعلومات.

تتحمّل شبكات التوسّط مسؤولية تشغيل سلسلة التوسّط وتحديد موقعها في سلسلة التوسّط. يتناول القسم التالي كيفية إعداد هذه العملية و تنفيذها.

استرداد سلسلة التوسّط وحدود عروض الأسعار

تتحمّل شبكة التوسّط مسؤولية استرداد الإعلانات السياقية للطرف الأول (1P) وسلسلة التوسّط وحدود عروض الأسعار للشبكات التابعة لجهات خارجية (3P). ويمكن أن يحدث ذلك في طلب لاسترداد الإعلانات السياقية التي تنفّذها شبكة التوسّط. تحدّد سلسلة التوسّط كيفية تكرار المرور عبر شبكات الجهات الخارجية، ويمكن تمرير حدود عروض الأسعار إلى عملية المزاد على النحو التالي: adSelectionSignals.

موضع الإعلان على الشبكة في سلسلة التوسّط

يمكن لحزمة تطوير البرامج (SDK) للتوسّط وضع نفسها في سلسلة التوسّط استنادًا إلى التكلفة الفعلية لكل ألف ظهور في الوقت الفعلي لعروض أسعار الإعلانات التابعة للطرف الأول. في Protected Audience API، تكون عروض أسعار الإعلانات غير شفافة. يجب أن تستخدم حزمة تطوير البرامج (SDK) لتوسّط AdSelectionFromOutcomesConfig لكي تتمكّن من مقارنة عرض سعر معيّن لإعلان طرف أول بحدّ أدنى عرض السعر لشبكة الطرف الثالث التالية في السلسلة. إذا كان عرض سعر الطرف الأول أعلى من الحدّ الأدنى لعرض السعر، يعني ذلك أنّ حزمة تطوير البرامج (SDK) لعملية التوسّط يتمّ وضعها أمام هذه الشبكة التابعة لجهة خارجية.

تنفيذ اختيار الإعلان

لاسترداد إعلان مرشح تابع للطرف الأول، يمكن لشبكة التوسّط تنفيذ مزاد على الجهاز باتّباع الخطوات الواردة في قسم تنفيذ اختيار الإعلان. يؤدّي ذلك إلى إنشاء إعلان مرشح تابع لجهة أولى وعرض سعر وAdSelectionId يتم استخدامه في عملية التوسّط.

أنشئ AdSelectionFromOutcomesConfig.

يسمح AdSelectionFromOutcomesConfig لشبكة التوسّط بتمرير قائمة بـ AdSelectionIds (النتائج من المزادات السابقة) وإشارات اختيار الإعلانات، و معرّف موارد منتظم (URI) لجلب JavaScript الذي يختار إعلانًا من عدّة إعلانات مرشحة. يتمّ تمرير قائمة AdSelectionIds مع عروض أسعارها والإشارات إلى JavaScript التي يمكنها عرض أحد AdSelectionIds إذا تفوّق على الحدّ الأدنى لعرض التسعير، أو لا تعرض أيًّا منها إذا كان من المفترض مواصلة سلسلة التوسّط.

تُنشئ شبكات التوسّط AdSelectionFromOutcomesConfig باستخدام AdSelectionId الطرف الأول من القسم السابق، وسعر عرض الحد الأدنى لشبكة الطرف الثالث قيد الاعتبار. يجب إنشاء AdSelectionFromOutcomesConfig جديد لكل خطوة في سلسلة التوسّط.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

يتطلّب إلغاء طريقة selectAds() للتوسّط في عرض الإعلانات بدون انقطاع إدخال AdSelectionFromOutcomesConfig، حيث يجب تحديد المَعلمات المطلوبة التالية:

• البائع: معرّف لشبكة إعلانات البائع التي تبدأ اختيار الإعلان.
• AdSelectionIds: قائمة فردية لتشغيل selectAds() سابق لإعلان تابع لجهة أولى.
• إشارات اختيار الإعلانات: عنصر JSON، يتم تسلسله كسلسلة، يحتوي على إشارات لاستخدامها في منطق عروض أسعار المشترين. في هذه الحالة، يجب تضمين الحدّ الأدنى لعرض السعر الذي تم استرجاعه للشبكة المحدّدة التابعة لجهة خارجية.
• معرّف الموارد المنتظم (URI) لمنطق الاختيار: عنوان URL لبروتوكول HTTPS يتمّ الاستعلام عنه أثناء اختيار الإعلان من أجل جلب JavaScript لشبكة التوسّط لاختيار إعلان فائِز. اطّلِع على نماذج الدوالّ المطلوبة في JavaScript. يجب أن يعرض JavaScript الإعلان التابع لجهة خارجية إذا كان عرض السعر أعلى من الحد الأدنى لعرض السعر، أو يعرض null في الحالات الأخرى. ويسمح ذلك لحزمة تطوير البرامج (SDK) للتوسّط بقطع سلسلة التوسّط عند العثور على استراتيجية فائزة.

بعد إنشاء AdSelectionOutcomesConfig، يمكنك استدعاء طريقة selectAds() في شبكة الجهة الخارجية التي تكون أولاً في السلسلة.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

تنظيم توسّط العرض الإعلاني بدون انقطاع

في ما يلي ترتيب العمليات التي يجب تنفيذها خلال عملية التوسّط.

1. شغِّل ميزة "اختيار الإعلانات من الطرف الأول".
2. كرِّر العملية في سلسلة التوسّط. بالنسبة إلى كل شبكة تابعة لجهة خارجية، اتّبِع الخطوات التالية:
   1. إنشاء AdSelectionFromOutcomeConfig بما في ذلك outcomeId من الطرف الأول وحدود عرض السعر لحزمة تطوير البرامج (SDK) التابعة للطرف الثالث
   2. اتصل برقم selectAds() باستخدام الإعدادات من الخطوة السابقة.
   3. إذا لم تكن النتيجة فارغة، أعِد عرض الإعلان.
   4. استخدِم طريقة selectAds() في محوِّل شبكة حزمة SDK الحالية. إذا كانت النتيجة غير فارغة، أعِد عرض الإعلان.
3. في حال عدم العثور على إعلان فائز من السلسلة، يتم عرض إعلان الطرف الأول.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

الإبلاغ عن مرّات ظهور الإعلانات

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

إعداد تقارير مرّات الظهور في خدمة SSP واحدة

بعد اختيار إعلان فائز من سير عمل اختيار الإعلانات، يمكنك الإبلاغ عن مرّة الظهور مرة أخرى إلى المنصات المشارِكة من جهة الشراء وجهة البيع باستخدام طريقة AdSelectionManager.reportImpression(). للإبلاغ عن مرّة ظهور إعلان:

1. شغِّل عنصر AdSelectionManager.
2. أنشئ عنصر ReportImpressionRequest باستخدام معرّف اختيار الإعلان.
3. استدِع الطريقة غير المتزامنة reportImpression() باستخدام كائن ReportImpressionRequest وكائنَي Executor و OutcomeReceiver ذات الصلة.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

اضبط ReportImpressionRequest باستخدام المَعلمات المطلوبة التالية:

• رقم تعريف اختيار الإعلان: رقم تعريف فريد لمستخدم الجهاز فقط يحدِّد اختيار إعلان ناجح.
• إعدادات اختيار الإعلان: الإعدادات نفسها المستخدَمة في selectAds() الطلب المحدَّد من خلال رقم تعريف اختيار الإعلان المقدَّم.

تستخدِم طريقة reportImpression() غير المتزامنة العنصر OutcomeReceiver للإشارة إلى نتيجة طلب البيانات من واجهة برمجة التطبيقات.

• يشير ردّ الاتصال onResult() إلى ما إذا تم إنشاء عناوين URL لإعداد تقارير مرّات الظهور وتحديد موعد للطلب.
• يشير ردّ الاتصال onError() إلى الحالات المحتملة التالية:
  • إذا تمّت بدء المكالمة باستخدام وسيطة إدخال غير صالحة، يشير الرمز AdServicesException إلى IllegalArgumentException كسبب.
  • تتلقّى جميع الأخطاء الأخرى رمز AdServicesException مع رمز IllegalStateException كسبب.

إعداد تقارير مرّات الظهور في توسّط العرض الإعلاني بدون انقطاع

يجب أن تتتبّع حزمة SDK لتوسّط الطلبات حزمة SDK الفائزة لبدء خطوات reporting flows. يجب أن توفّر حِزم تطوير البرامج (SDK) المشارِكة في سلسلة التوسّط أسلوبًا يمكن للوسيط استخدامه لبدء عملية إعداد التقارير الخاصة به. يمكن لحزمة تطوير البرامج (SDK) التي تشارك في مزاد توسّط اتّباع الخطوات المذكورة أعلاه لتنفيذ ميزة إعداد التقارير الخاصة بها.

يمكن لخدمات عرض الإعلانات استخدام مثال رمز حزمة تطوير البرامج (SDK) التابعة لجهة خارجية هذا كنموذج أولي لكيفية الانضمام إلى تدفقات التوسّط:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

نقاط نهاية إعداد تقارير مرّات الظهور

تُصدر واجهة برمجة التطبيقات لظهور الإعلانات في التقارير طلبات HTTPS GET إلى نقاط النهاية التي تقدّمها منصّة جهة البيع والمنصّة الفائزة لجهة الشراء:

نقطة نهاية منصة جهة الشراء:

• تستخدِم واجهة برمجة التطبيقات عنوان URL لمنطق عروض الأسعار المحدّد في شريحة الجمهور المخصّصة لتحميل رمز JavaScript المقدَّم من المشتري الذي يتضمّن منطقًا لعرض عنوان URL لإعداد تقارير مرّات الظهور.
• استخدِم دالة JavaScript‏ reportWin() التي من المتوقّع أن تعرِض عنوان URL لتقرير مرّات ظهور المشتري.

نقطة نهاية وسيط عرض المبيعات:

• استخدِم عنوان URL لمنطق القرار المحدّد في عنصر AdSelectionConfig لجلب رمز JavaScript لمنطق القرار الخاص بالبائع.
• استخدِم دالة JavaScript‏ reportResult() التي من المتوقّع أن تعرِض عنوان URL لتقرير مرّات الظهور الخاص بالبائع.

إعداد تقارير خدمات عروض الأسعار والمزادات

سيتضمّن المزاد الذي يتم تنفيذه في خدمات عروض الأسعار والمزادات كلّ الخطوات اللازمة لإعداد التقارير، بما في ذلك عناوين URL التي تم إنشاؤها من أجل إعداد تقارير التفاعل مع الإعلانات، والتي يتم تضمينها في الردّ المشفّر من المزاد من جهة الخادم. عند فك تشفير الردّ، يتم تسجيل عناوين URL المناسبة في المنصة، لذا يتم اتّباع الخطوات نفسها في إعداد تقارير الإعلانات ومرّات الظهور.

تقارير مرّات الظهور وفقًا لأفضل جهد

تم تصميم طريقة reportImpression() لتقديم أفضل جهد ممكن لإكمال عملية إعداد التقارير.

الإبلاغ عن التفاعلات مع الإعلانات

توفّر ميزة "الجمهور المحمي" إمكانية إعداد تقارير عن التفاعلات الأكثر دقة ل إعلان معروض. يمكن أن تتضمّن هذه التفاعلات وقت المشاهدة أو النقرات أو التمريرات فوق المحتوى أو أي مقياس آخر مفيد يمكن جمعه. تتطلّب عملية تلقّي هذين التقريرَين خطوتَين. أولاً، على المشترين والبائعين التسجيل لتلقّي هذه التقارير في JavaScript لإعداد التقارير. بعد ذلك، على العميل الإبلاغ عن هذه الأحداث.

التسجيل لتلقّي أحداث التفاعل

يتم تسجيل أحداث التفاعل في دالّتَي JavaScript reportWin() الخاصة بالمشتري reportResult() الخاصة بالبائع باستخدام دالّة JavaScript تقدّمها المنصة: registerAdBeacon. للتسجيل لتلقّي ملف ناتج عن الأحداث، استخدِم وظيفة JavaScript الخاصة بالمنصة من ملف ناتج عن JavaScript الخاص بالتقارير. يستخدم المقتطف التالي reportWin() الخاص بالمشتري، ولكن ينطبق الأسلوب نفسه على reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

الإبلاغ عن أحداث التفاعل

بعد الإبلاغ عن مرّة ظهور، يمكن للعملاء الإبلاغ عن التفاعلات مرة أخرى إلى المنتديات الفائزة المسجّلة مسبقًا من جهة الشراء والبيع باستخدام AdSelectionManager.reportInteraction(). للإبلاغ عن حدث إعلاني:

1. شغِّل عنصر AdSelectionManager.
2. أنشئ عنصر ReportInteractionRequest باستخدام معرّف اختيار الإعلان، ومفتاح التفاعل، وبيانات التفاعل، ووجهة إعداد التقارير.
3. استدِع الطريقة غير المتزامنة reportInteraction() باستخدام الكائن request والكائنَين Executor وOutcomeReceiver ذات الصلة.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

اضبط ReportInteractionRequest باستخدام المَعلمات المطلوبة التالية:

• معرّف اختيار الإعلان: معرّف اختيار إعلان تم استرجاعه من ملف شخصي تم عرضه سابقًا AdSelectionOutcome.
• مفتاح التفاعل: مفتاح سلسلة يحدّده العميل يصف الإجراء الذي يتم تسجيله. يجب أن يتطابق هذا المفتاح مع المفتاح الذي سجّله البائع أو العميل في دوالّ JavaScript لإعداد التقارير.
• بيانات التفاعل: سلسلة تحتوي على بيانات ليتم تضمينها في تقرير الحدث، ليتم إرسالها مرة أخرى إلى خوادم إعداد التقارير.
• الوجهات التي يتم الإبلاغ عنها: قناع بت يحدّد ما إذا كان يجب إعلام العميل أو البائع أو كليهما بالأحداث. يوفّر الطور الأساسي هذه العلامات، ويمكن إنشاء قناع الوجهة النهائية باستخدام عمليات التحويل الثنائي. للإبلاغ عن وجهة واحدة، يمكنك استخدام العلامة التي تقدّمها منصّة التطوير مباشرةً. للإبلاغ عن وجهات متعددة، يمكنك استخدام عامل التشغيل المبرمَج OR (|) لدمج قيم العلامة.

تستخدِم طريقة reportInteraction() غير المتزامنة العنصر OutcomeReceiver للإشارة إلى نتيجة طلب البيانات من واجهة برمجة التطبيقات.

• يشير المرجع onResult() إلى أنّ طلب التفاعل الذي تم الإبلاغ عنه صالح.
• يشير ردّ الاتصال onError() إلى الحالات المحتملة التالية:
  • إذا تم إجراء المكالمة عندما يكون التطبيق قيد التشغيل في الخلفية، يتم عرض IllegalStateException مع وصف للتعطُّل.
  • إذا تم إيقاف العميل عن الاتصال بـ reportInteraction()، يتم عرض LimitExceededException.
  • إذا لم تكن الحزمة مسجّلة للاتّصال بواجهات برمجة التطبيقات التي تحافظ على الخصوصية، يتم عرض القيمة SecurityException().
  • إذا كان التطبيق الذي يُبلغ عن التفاعلات مختلفًا عن التطبيق الذي استدعى selectAds()، يتم عرض IllegalStateException.
• إذا لم يوافق المستخدم على تفعيل واجهات برمجة تطبيقات Privacy Sandbox API، لن يتم إظهار أي رسالة خطأ عند تعذُّر إكمال الطلب.

نقاط نهاية إعداد تقارير التفاعل

تُصدر واجهة برمجة التطبيقات Report Interaction API طلبات POST عبر HTTPS إلى نقاط النهاية التي تقدّمها منصة جهة البيع والمنصة الفائزة من جهة الشراء. ستطابق ميزة "شريحة الجمهور المحمية" مفاتيح التفاعل مع عناوين URL المُعلَن عنها في JavaScript لإعداد التقارير، وستُصدر طلب POST إلى كل نقطة نهاية لكل تفاعُل يتم تسجيله. Content-Type الطلب هو نص عادي مع النص الأساسي وهو بيانات التفاعل.

تقارير التفاعل بالاستناد إلى أفضل الجهود

تم تصميم reportInteraction() لتقديم أفضل جهد ممكن لإكمال reporting من خلال HTTP POST.

التحديث اليومي في الخلفية

عند إنشاء شريحة جمهور مخصّصة، يمكن لتطبيقك أو حزمة SDK إعداد metadata لشريحة الجمهور المخصّصة. بالإضافة إلى ذلك، يمكن للمنصة تعديل العناصر التالية من البيانات الوصفية المخصّصة للجمهور من خلال عملية تعديل يومية في الخلفية.

• إشارات عروض أسعار المستخدِمين
• بيانات عروض الأسعار الموثوق بها
• قائمة واحدة (AdData)

تُجري هذه العملية طلبات بحث عن عنوان URL للتعديل اليومي المحدّد في شريحة الجمهور المخصّصة، وقد يعرض عنوان URL استجابة JSON.

• قد يحتوي ردّ JSON على أيّ من حقول البيانات الوصفية المتوافقة التي تحتاج إلى التحديث.
• يتم التحقّق من صحة كل حقل JSON بشكل مستقل. يتجاهل العميل أيّ حقول ذات تنسيق غير صحيح، ما يؤدي إلى عدم إجراء أي تعديلات على ذلك الحقل المحدّد في الردّ.
• لا يؤدي استجابة HTTP فارغة أو عنصر JSON فارغ "{}" إلى تعديل البيانات الوصفية.
• يجب ألا يزيد حجم رسالة الردّ عن 10 كيلوبايت.
• يجب استخدام بروتوكول HTTPS في جميع معرّفات الموارد المنتظمة (URI).
• يجب أن يتشارك trusted_bidding_uri مع المشتري عنوان ETLD+1 نفسه.

مثال: استجابة JSON للتعديل اليومي في الخلفية

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript لاختيار الإعلانات

تنظّم سير العمل لاختيار الإعلانات تنفيذ رمز JavaScript المقدَّم من المشتري والمقدَّم من البائع.

يتم جلب JavaScript المقدَّمة من المشتري من عنوان URL لمنطق عروض الأسعار المحدّد في شريحة الجمهور المخصّصة. يجب أن تتضمّن JavaScript المعروضة الدوالّ التالية:

• generateBid()
• reportWin()

يتم جلب JavaScript المقدَّم من البائع من عنوان URL لمنطق القرار المحدّد في AdSelectionConfig لمقدّمة واجهة برمجة التطبيقات لاختيار الإعلانات. يجب أن يتضمّن رمز JavaScript المعروض الوظائف التالية:

• scoreAd()
• reportResult()

generateBid()‎

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

مَعلمات الإدخال:

• ad: عنصر JSON بالتنسيق var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: كائنات JSON المحدّدة في كائن إعدادات المزاد

• custom_audience_bidding_signals: عنصر JSON تم إنشاؤه من خلال المنصة. تنسيق كائن JSON هذا هو:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  حيث:

  • owner وbuyer وname هي سلاسل يتمّ أخذها من المواقع التي تحمل اسمًا مماثلاً للجمهور المخصّص الذي يشارك في اختيار الإعلان.
  • activation_time وexpiration_time هما وقت تفعيل الجمهور المخصّص و انتهاء صلاحيته، ويتم التعبير عنهما بالثواني منذ بداية حقبة نظام التشغيل Unix.
  • ca_user_bidding_signals هي سلسلة JSON محدّدة في حقل userBiddingSignals من CustomAudience في وقت الإنشاء.
  • trusted_bidding_signals, contextual_signals وuser_signals هما كائنان بتنسيق JSON. ويتم تمريرها كعناصر فارغة وسيتم ملؤها في الإصدارات المستقبلية. ولا تفرض المنصة تنسيقها، بل تُدار من خلال تكنولوجيا الإعلان.

النتيجة:

• ‫ad: هو الإعلان الذي يشير إليه عرض السعر. يُسمح للنص البرمجي بإرجاع نسخة من الإعلان الذي تلقّاه مع بيانات وصفية مختلفة. من المتوقّع ألا يتم تغيير السمة render_url لإعلان.
• bid: قيمة عددية عائمة تمثّل قيمة عرض السعر لهذا الإعلان
• ‫status: قيمة عددية يمكن أن تكون:
  • 0: لتنفيذ العملية بنجاح
  • 1: (أو أي قيمة غير صفرية) في حال كانت أي من إشارات الإدخال غير صالحة. فيحال عرض قيمة غير صفرية من خلال generate-bid، يتم إبطال عملية تقديم عروض الأسعار لجميع إعلانات "شبكة البحث الإعلانية".

scoreAd()‎

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

مَعلمات الإدخال:

• ad: اطّلِع على مستندات generateBid.
• bid: قيمة عرض السعر للإعلان

• ad_selection_config: عنصر JSON يمثّل المَعلمة AdSelectionConfig لواجهة برمجة التطبيقات selectAds. التنسيق هو:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals: عناصر JSON التي يتم قراءتها من مَعلمة واجهة برمجة التطبيقات sellerSignals AdSelectionConfig

• trusted_scoring_signal: القراءة من حقل adSelectionSignals في مَعلمة واجهة برمجة التطبيقات AdSelectionConfig

• ‫contextual_signals, user_signals: كائنات JSON ويتم تمريرها على أنّها عناصر فارغة وسيتم ملؤها في الإصدارات المستقبلية. ولا تفرض المنصة شكلها، بل تُدار من خلال تكنولوجيا الإعلان.

• per_buyer_signals: عنصر JSON الذي تم قراءته من خريطة perBuyerSignal في مَعلمة واجهة برمجة التطبيقات AdSelectionConfig باستخدام مشتري Custom Audience الحالي كمفتاح فارغة إذا لم تحتوي الخريطة على أي إدخال للمشتري المعنيّ

إخراج:

• score: قيمة عددية عائمة تمثّل قيمة النتيجة لهذا الإعلان
• ‫status: قيمة عددية يمكن أن تكون:
  • 0: لإجراء عملية تنفيذ ناجحة
  • 1: في حال كانت customAudienceSignals غير صالحة
  • 2: في حال كانت قيمة AdSelectionConfig غير صالحة
  • 3: في حال كانت أي من الإشارات الأخرى غير صالحة
  • تؤدي أي قيمة غير صفرية إلى تعذُّر العملية، وتحدِّد القيمة نوع الاستثناء الذي يتم طرحه.

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

مَعلمات الإدخال:

• outcomes: عنصر JSON {"id": id_string, "bid": bid_double}
• selection_signals: كائنات JSON المحدّدة في إعدادات المزاد object

إخراج:

• ‫status: 0 للنجاح، قيمة غير صفرية في حال حدوث خطأ
• result: أحد النتائج التي تم تمريرها أو قيمة فارغة

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

مَعلمات الإدخال:

• ad_selection_config: اطّلِع على مستندات scoreAds.
• ‫render_url: عنوان URL لعرض الإعلان الفائز
• bid: عرض السعر المقدَّم للإعلان الفائز
• contextual_signals: اطّلِع على مستندات generateBid.

إخراج:

• status: 0 للنجاح وقيمة غير صفرية للتعذّر
• ‫results: عناصر JSON تحتوي على ما يلي:
  • signals_for_buyer: عنصر JSON يتم تمريره إلى الدالة reportWin
  • ‫reporting_url: عنوان URL يستخدِمه النظام الأساسي لإرسال إشعار بشأن مرّة الظهور إلى المشتري

reportWin()‎

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

مَعلمات الإدخال:

• ad_selection_signals, per_buyer_signals: راجِع المستندات المتعلّقة بملف scoreAd.
• signals_for_buyer: عنصر JSON تم إرجاعه بواسطة reportResult
• contextual_signals, custom_audience_signals: اطّلِع على المستندات المتعلّقة بـ generateBid.

إخراج:

• status: 0 للنجاح وقيمة غير صفرية للتعذّر
• ‫results: عنصر JSON يحتوي على ما يلي:
  • reporting_url: عنوان URL تستخدِمه المنصة لإرسال إشعار بشأن مرّة الظهور إلى البائع

registerAdBeacon()

function registerAdBeacon(
  beacons
)

مَعلمات الإدخال:

• beacons: عنصر يحتوي على أزواج مفتاح/قيمة لمفاتيح التفاعل ومقاييس قياس الأداء ومعرّفات الموارد المنتظمة لإعداد التقارير التنسيق هو:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • ‫interaction_key: سلسلة تمثّل الحدث ويستخدم ال منصّة هذا الإجراء لاحقًا عند إعداد تقارير عن تفاعلات الأحداث للبحث عن reporting_uri التي يجب إعلامها. يجب أن يتطابق هذا المفتاح بين ما يسجّله المشتري أو البائع وما يُبلغ عنه البائع.
  • ‫reporting_uri: معرّف موارد منتظم لتلقّي تقارير الأحداث يجب أن يكون هذا الوصف محدّدًا لنوع الحدث الذي يتم الإبلاغ عنه. يجب أن يقبل طلب POST لمعالجة أي بيانات يتم الإبلاغ عنها مع الحدث.

  على سبيل المثال:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

معرّفات الموارد المنتظمة (URI) المُنشأة مسبقًا لميزة "اختيار الإعلان"

تمنح عناوين URL المُنشأة مسبقًا لتقنيات الإعلان إمكانية تعيين دوالّ JavaScript لمنطق اتّخاذ قرار اختيار الإعلان في فئتَي AdSelectionConfig و AdSelectionFromOutcomesConfig. لا تتطلّب معرّفات الموارد المنتظِمة المُنشأة مسبقًا طلبات للشبكة لتنزيل JavaScript المقابل. يمكن لتكنولوجيات عرض الإعلانات استخدام معرّفات الموارد المنتظمة المُنشأة مسبقًا بدون الحاجة إلى إعداد نطاق مسجّل لاستضافة JavaScript.

يتم إنشاء عنوان URL مُعدّ مسبقًا باستخدام التنسيق التالي:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

توفّر منصّة "مبادرة حماية الخصوصية" JavaScript باستخدام المعلومات الواردة من ملف تعريف الارتباط URI هذا في وقت التشغيل.

يتم طرح IllegalArgumentException في الحالات التالية:

• عدم توفّر أي من المَعلمات المطلوبة في معرّف الموارد المنتظم
• هناك مَعلمات غير معروفة في معرّف الموارد المنتظم (URI).

أسماء وحالات استخدام عناوين URL المُنشأة مسبقًا المتوافقة

حالة الاستخدام 1: اختيار الإعلانات

تتوفّر معرّفات الموارد المنتظمة (URI) المُنشأة مسبقًا ضمن حالة الاستخدام ad-selection في عملية selectAds(AdSelectionConfig).

اسم معرّف الموارد المنتظم (URI) المُنشئ مسبقًا: highest-bid-wins

يقدّم عنوان URL المُنشئ مسبقًا رمز JavaScript يختار الإعلان الذي يقدّم أعلى عرض سعر بعد تقديم عروض الأسعار. وتوفّر أيضًا وظيفة إعداد تقارير أساسية للإبلاغ عن render_uri وbid الفائزَين.

المَعلمات المطلوبة

reportingUrl: عنوان URL الأساسي لإعداد التقارير الذي تمّت برمجته باستخدام render_uri وbid للإعلان الفائز:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

الاستخدام

إذا كان عنوان URL الأساسي لإعداد التقارير هو https://www.ssp.com/reporting، سيكون عنوان URI المُنشأ مسبقًا هو:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

حالة الاستخدام 2: اختيار الإعلانات حسب النتائج

تتيح معرّفات الموارد المنتظمة (URI) المُنشأة مسبقًا ضِمن حالة الاستخدام ad-selection-from-outcomes سير العمل selectAds(AdSelectionFromOutcomesConfig).

اسم معرّف الموارد المنتظم (URI) المُنشئ مسبقًا: waterfall-mediation-truncation

يقدّم عنوان URL المُنشئ مسبقًا waterfall-mediation-truncation رمز JavaScript الذي ينفّذ منطق اقتطاع التوسّط في العرض الإعلاني بدون انقطاع، حيث يعرض رمز JavaScript إعلانًا تابعًا لجهة خارجية إذا كانbid أعلى منbid floor أو يساويه، ويعرضnull في الحالات الأخرى.

المَعلمات المطلوبة

bidFloor: مفتاح قيمة الحدّ الأدنى لعرض السعر الذي تم تمريره في getSelectionSignals() الذي تتم مقارنته بالإعلان في حزمة تطوير البرامج (SDK) للتوسّط.

الاستخدام

إذا كانت إشارات اختيار الإعلانات تبدو على النحو التالي {"bid_floor": 10}، سيكون معرّف URI المُعدّ مسبقًا الناتج على النحو التالي:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

الاختبار

لمساعدتك في البدء باستخدام Protected Audience API، أنشأنا عيّنات تطبيقات بلغتَي Kotlin وJava، ويمكن العثور عليها على GitHub.

المتطلبات الأساسية

تتطلّب Protected Audience API بعض JavaScript أثناء اختيار الإعلانات و reporting. impression هناك طريقتان لتقديم JavaScript هذا في بيئة اختبار:

• تشغيل خادم يتضمّن نقاط نهاية HTTPS المطلوبة التي تعرض JavaScript
• إلغاء عملية الجلب عن بُعد من خلال تقديم الرمز اللازم من مصدر محلي

يتطلّب أيّ من الأسلوبَين إعداد نقطة نهاية HTTPS لمعالجة ملفّات تقارير مرّات الظهور.

نقاط نهاية HTTPS

لاختبار اختيار الإعلانات وإعداد تقارير مرّات الظهور، عليك إعداد 7 نقاط نهاية لخدمة HTTPS يمكن للجهاز الاختباري أو المحاكي الوصول إليها:

1. نقطة نهاية المشتري التي تعرِض JavaScript لمنطق عروض الأسعار
2. نقطة نهاية تعرض إشارات عروض الأسعار.
3. نقطة نهاية البائع التي تعرِض JavaScript لمنطق القرار
4. نقطة نهاية تعرِض إشارات التسجيل
5. نقطة نهاية إعداد تقارير مرّات الظهور الفائزة للمشترين
6. نقطة نهاية إعداد تقارير مرّات الظهور للبائع
7. نقطة نهاية لعرض التحديثات اليومية لشريحة جمهور مخصّصة

لتسهيل الأمر، يقدّم مستودع GitHub رمز JavaScript أساسيًا لأغراض الاختبار. ويشمل أيضًا تعريفات خدمات OpenAPI التي يمكن نشرها على منصّة متوافقة لمحاكاة الخدمات أو الخدمات المصغرة. لمزيد من التفاصيل، يُرجى الاطّلاع على ملف README الخاص بالمشروع.

إلغاء جلب JavaScript عن بُعد

هذه الميزة مخصّصة للاستخدام في الاختبار الشامل. لإلغاء عملية التحميل عن بُعد، يجب تشغيل تطبيقك في وضع تصحيح الأخطاء مع تفعيل خيارات المطوّرين.

لتفعيل وضع تصحيح الأخطاء لتطبيقك، أضِف السطر التالي إلى سمة application في ملف AndroidManifest.xml:

<application
  android:debuggable="true">

للحصول على مثال على كيفية استخدام عمليات الاستبدال هذه، اطّلِع على نموذج تطبيق Protected Audience API على GitHub.

عليك إضافة رمز JavaScript المخصّص الخاص بك للتعامل مع إجراءات اختيار الإعلانات، مثل عروض الأسعار وقرارات التقييم وإعداد التقارير. يمكنك العثور على أمثلة رمز JavaScript أساسي تعالج جميع الطلبات المطلوبة في مستودع GitHub. يوضّح نموذج تطبيق Protected Audience API كيفية قراءة الرمز من هذا الملف وإعداده لاستخدامه كاستثناء.

من الممكن إلغاء جلب JavaScript من جهة البيع والشراء بشكل مستقل، ولكنك تحتاج إلى نقطة نهاية HTTPS لعرض أي JavaScript لا تقدّم لها إلغاء. اطّلِع على ملف README للحصول على معلومات عن كيفية إعداد خادم يعالج هذه الحالات.

لا يمكن إلغاء جلب JavaScript إلا لشرائح الجمهور المخصّصة التي تملكها حِزمك.

إلغاء وحدات JavaScript من جهة البيع

لإعداد عملية إلغاء لرمز JavaScript على جهة البيع، اتّبِع الخطوات التالية كما هو موضّح في مثال التعليمة البرمجية التالي:

1. شغِّل عنصر AdSelectionManager.
2. الحصول على مرجع إلى TestAdSelectionManager من عنصر AdSelectionManager
3. أنشئ عنصر AdSelectionConfig.
4. أنشئ AddAdSelectionOverrideRequest باستخدام كائن AdSelectionConfig وString الذي يمثّل JavaScript الذي تريد استخدامه كعنصر إلغاء.
5. استدِع الطريقة غير المتزامنة overrideAdSelectionConfigRemoteInfo() باستخدام كائن AddAdSelectionOverrideRequest وكائنَي Executor وOutcomeReceiver ذات الصلة.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

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

لإلغاء JavaScript المستخدَم أثناء اختيار الإعلان، يجب أن يحتوي الرمز البرمجي decisionLogicJs على نماذج الدوال البرمجية المناسبة من جهة البائع. للحصول على مثال على كيفية قراءة ملف JavaScript كسلسلة، اطّلِع على نموذج تطبيق Protected Audience API على GitHub.

تستخدِم الطريقة غير المتزامنة overrideAdSelectionConfigRemoteInfo() العنصر OutcomeReceiver للإشارة إلى نتيجة طلب البيانات من واجهة برمجة التطبيقات.

يشير ردّ الاتصال onResult() إلى أنّه تم تطبيق التجاوز بنجاح. ستستخدم المكالمات المستقبلية إلى selectAds() أيّ منطق اتّخاذ قرارات وإعداد تقارير تم ضبطه كخيار إلغاء.

يشير طلب إعادة الاتصال onError() إلى شرطَين محتمَلَين:

• إذا تمّت محاولة إلغاء الإعدادات باستخدام وسيطات غير صالحة، يشير الرمز AdServiceException إلى IllegalArgumentException باعتباره السبب.
• إذا تمّت محاولة إلغاء الإعدادات باستخدام تطبيق لا يعمل في وضع تصحيح الأخطاء مع تفعيل خيارات المطوّرين، يشير رمز AdServiceException إلى IllegalStateException كسبب لذلك.

إعادة ضبط عمليات إلغاء الإعدادات من جهة البيع

يفترض هذا القسم أنّك تجاوزت JavaScript على جهة البيع وأنّه لديك إشارة إلى TestAdSelectionManager و AdSelectionConfig المستخدَمة في القسم السابق.

لإعادة ضبط عمليات إلغاء الإعدادات لجميع AdSelectionConfigs:

1. استخدِم الطريقة غير المتزامنة resetAllAdSelectionConfigRemoteOverrides() مع الكائن OutcomeReceiver ذي الصلة.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

بعد إعادة ضبط عمليات إلغاء البيانات من جهة البيع، تستخدِم طلبات البيانات إلى selectAds() أيّ decisionLogicUrl يتم تخزينه في AdSelectionConfig لمحاولة جلب JavaScript المطلوبة.

إذا تعذّر الاتصال بـ resetAllAdSelectionConfigRemoteOverrides()، يقدّم الإجراء المغلق OutComeReceiver.onError() AdServiceException. إذا تمّت محاولة إزالة عمليات الاستبدال باستخدام تطبيق لا يعمل في وضع تصحيح الأخطاء مع تفعيل خيارات المطوّرين، يشير AdServiceException إلى IllegalStateException كسبب لذلك.

إلغاء وحدات JavaScript على جهة الشراء

1. اتّبِع الخطوات للانضمام إلى شريحة جمهور مخصّصة.
2. أنشئ AddCustomAudienceOverrideRequest باستخدام المشتري والاسم لشريحة الجمهور المخصّصة التي تحتاج إلى إلغاء إعداداتها، بالإضافة إلى منطق عروض الأسعار والبيانات التي تريد استخدامها كإعدادات إلغاء.
3. استدِع الطريقة غير المتزامنة overrideCustomAudienceRemoteInfo() باستخدام كائن AddCustomAudienceOverrideRequest وكائنَي Executor وOutcomeReceiver ذات الصلة.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

قيم المشتري والاسم هي القيم نفسها المستخدَمة لإنشاء شريحة الجمهور المخصّصة. مزيد من المعلومات حول هذه الحقول

بالإضافة إلى ذلك، يمكنك تحديد مَعلمتَين إضافيتَين:

• biddingLogicJs: JavaScript الذي يحتوي على منطق المشتري الذي يتم استخدامه أثناء اختيار الإعلان اطّلِع على نماذج الدوالّ المطلوبة في ملف JavaScript.
• ‫trustedBiddingSignals: إشارات عروض الأسعار التي سيتم استخدامها أثناء اختيار الإعلان. لأغراض الاختبار، يمكن أن تكون سلسلة فارغة.

تستخدِم الطريقة غير المتزامنة overrideCustomAudienceRemoteInfo() العنصر OutcomeReceiver للإشارة إلى نتيجة طلب البيانات من واجهة برمجة التطبيقات.

يشير ردّ الاتصال onResult() إلى أنّه تم تطبيق التجاوز بنجاح. تستخدِم الطلبات اللاحقة إلى selectAds() أيّ منطق لعروض الأسعار وإعداد التقارير تم تمريره كقيمة إلغاء.

يشير طلب إعادة الاتصال onError() إلى حالتَين محتملتَين.

• إذا تمّت محاولة إلغاء الإعدادات باستخدام وسيطات غير صالحة، يشير الرمز AdServiceException إلى IllegalArgumentException باعتباره السبب.
• إذا تمّت محاولة إلغاء الإعدادات باستخدام تطبيق لا يعمل في وضع تصحيح الأخطاء مع تفعيل خيارات المطوّرين، يشير رمز AdServiceException إلى IllegalStateException كسبب لذلك.

إعادة ضبط عمليات إلغاء الإعدادات من جهة الشراء

يفترض هذا القسم أنّك تجاوزت JavaScript في جهة الشراء وأنّه لديك إشارة إلى TestCustomAudienceManager المستخدَمة في القسم السابق.

لإعادة ضبط عمليات الاستبدال لجميع شرائح الجمهور المخصّصة:

1. استدِع الطريقة غير المتزامنة resetAllCustomAudienceOverrides() باستخدام كائنَي Executor وOutcomeReceiver المناسبَين.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

بعد إعادة ضبط عمليات إلغاء الإعدادات من جهة الشراء، تستخدِم الطلبات اللاحقة إلى selectAds() أيّ biddingLogicUrl وtrustedBiddingData مخزّن في CustomAudience لمحاولة جلب ملف JavaScript المطلوب.

إذا تعذّر الاتصال بـ resetCustomAudienceRemoteInfoOverride()، يقدّم الإجراء المُعاد توجيهه إلى OutComeReceiver.onError() AdServiceException. إذا تمّت محاولة إزالة عمليات الاستبدال باستخدام تطبيق لا يعمل في وضع تصحيح الأخطاء مع تفعيل خيارات المطوّرين، يشير رمز AdServiceException إلى IllegalStateException كسبب لذلك.

إعداد خادم تقارير

عند استخدام عمليات إلغاء الجلب عن بُعد، سيظل عليك إعداد خادم يمكن لجهازك أو المحاكي الوصول إليه للردّ على أحداث إعداد التقارير. إنّ نقطة نهاية تعرض القيمة 200 كافية للاختبار. يتضمّن مستودع GitHub تعريفات خدمات OpenAPI التي يمكن نشرها على منصة تطبيقات مصغّرة أو محاكاة متوافقة. لمزيد من التفاصيل، يُرجى الاطّلاع على ملف README الخاص بالمشروع.

عند البحث عن تعريفات OpenAPI، ابحث عن reporting-server.json. يحتوي هذا الملف على نقطة نهاية تعرض القيمة 200، والتي تمثّل رمز استجابة HTTP. يتم استخدام نقطة النهاية هذه أثناء selectAds() وتُرسِل إشارة إلى Protected Audience API بأنّه تم إكمال إعداد تقارير مرّات الظهور بنجاح.

الوظائف المطلوب اختبارها

• يمكنك ممارسة الانضمام إلى شريحة جمهور مخصّصة أو مغادرتها وإعدادها استنادًا إلى إجراءات المستخدِم السابقة.
• بدء اختيار الإعلانات على الجهاز من خلال رمز JavaScript مستضاف عن بُعد
• راقِب كيف يمكن أن يؤثّر ربط التطبيق بإعدادات شرائح الجمهور المخصّصة في نتائج اختيار الإعلانات.
• اطّلِع على تقارير مرّات الظهور بعد اختيار الإعلان.

القيود

يسرد الجدول التالي القيود المفروضة على معالجة Protected Audience API. قد تتغيّر الحدود المعروضة استنادًا إلى الملاحظات والآراء. للاطّلاع على الميزات قيد التطوير، يُرجى قراءة ملاحظات الإصدار.

الإبلاغ عن الأخطاء والمشاكل

ملاحظاتك هي جزء مهم من "مبادرة حماية الخصوصية" على Android. يُرجى إعلامنا بأي مشاكل تواجهها أو أفكار لتحسين "مبادرة حماية الخصوصية" على Android.