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

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

لاستخدام ميزة تحديد عدد مرّات الظهور في مزادك، عليك أولاً إنشاء عناصر 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();

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

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

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

لتحسين وقت الاستجابة، يمكن لتكنولوجيات الإعلان تنفيذ عملية اختيار إعلانات تتضمّن فقط الإعلانات السياقية مع وظيفة فلترة الإعلانات بدون طلبات بيانات من الشبكة. ويتمّ تحقيق ذلك باستخدام معرّفات الموارد المنتظمة (URI) المُنشأة مسبقًا لتحديد علامات الأداء. راجِع قسم حالات الاستخدام والأسماء المتوافقة للعناوين المؤدية الكاملة المُنشأة مسبقًا للحصول على قائمة بعمليات 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 للتقارير أثناء استخدام معرّفات الموارد المنتظِمة مسبقًا

في الوقت الحالي، تتضمّن منصة "مبادرة حماية الخصوصية" تنفيذًا أساسيًا لإعداد التقارير باستخدام 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).

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

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

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

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

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. للحصول على مزيد من المعلومات، يمكنك الرجوع إلى الأقسام المتعلقة بكيفية اختيار الإعلانات وكيفية الإبلاغ عن مرات ظهور الإعلان.

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

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

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

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

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

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

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

إنشاء AdSelectionFromResultsConfig

يسمح 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) وتنفّذ مزادًا، يمكنك متابعة هذا القسم. إذا كان سيتم تنفيذ التوسّط في العرض الإعلاني بدون انقطاع، اتّبِع الخطوات الواردة في قسم إعداد تقارير مرّات الظهور في التوسّط في العرض الإعلاني بدون انقطاع.

إعداد تقارير مرّات الظهور في خدمة 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) المشارِكة في سلسلة التوسّط أسلوبًا يمكن للوسيط استخدامه لبدء عملية إعداد التقارير الخاصة به. يمكن لحزمة تطوير البرامج (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() لتقديم أفضل جهد ممكن لإكمال reporting.

إعداد تقارير عن التفاعلات مع الإعلانات

توفّر ميزة "شريحة الجمهور المحمية" إمكانية إعداد تقارير عن التفاعلات الأكثر دقة ل إعلان معروض. يمكن أن تتضمّن هذه التفاعلات وقت المشاهدة أو النقرات أو التمريرات فوق المحتوى أو أي مقياس آخر مفيد يمكن جمعه. تتطلب عملية تلقي هذه التقارير خطوتين. أولاً، يجب على المشترين والبائعين التسجيل لتلقّي هذه التقارير في 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 إلى كل نقطة نهاية لكل تفاعُل يتم تسجيله. نوع محتوى الطلب هو نص عادي مع النص الذي يمثّل بيانات التفاعل.

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

تم تصميم reportInteraction() لتوفير أفضل جهد لإكمال عملية إعداد التقارير من خلال طريقة HTTP POST.

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

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

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

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

• قد يحتوي ردّ JSON على أيّ من حقول البيانات الوصفية المتوافقة التي تحتاج إلى التحديث.
• يتم التحقّق من صحة كل حقل JSON بشكل مستقل. يتجاهل العميل أيّ حقول ذات تنسيق غير صحيح، ما يؤدي إلى عدم إجراء أي تعديلات على هذا الحقل المحدّد في الاستجابة.
• يؤدي استخدام استجابة HTTP فارغة أو كائن JSON فارغ "{}" إلى عدم تعديل البيانات الوصفية.
• يجب ألا يزيد حجم رسالة الردّ عن 10 كيلوبايت.
• يلزم استخدام جميع معرفات الموارد المنتظمة (URI) لاستخدام HTTPS.
• يجب أن يشارك "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 API. التنسيق هو:

  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 المحدّدة في كائن إعدادات المزاد

إخراج:

• 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: كائن يحتوي على أزواج المفتاح/القيمة من مفاتيح التفاعل ومعرّفات الموارد المنتظمة (URI) لإعداد التقارير. التنسيق هو:

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

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

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

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

معرّفات الموارد المنتظِمة مسبقًا لتحديد الإعلانات

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

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

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

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

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

• عدم وجود أي من المعلمات المطلوبة في عنوان URI
• توجد معلمات غير معروفة في معرف الموارد المنتظم (URI)

حالات استخدام معرف الموارد المنتظم (URI) المتوافقة وأسماؤهما

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

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

اسم معرِّف الموارد المنتظم (URI) الذي تم إنشاؤه مسبقًا: highest-bid-wins

يوفّر معرّف الموارد المنتظم (URI) المُنشأ مسبقًا برنامج 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 أثناء اختيار الإعلانات وإعداد تقارير مرّات الظهور. هناك طريقتان لتقديم JavaScript هذا في بيئة اختبار:

• تشغيل خادم يحتوي على نقاط نهاية HTTPS المطلوبة التي تعرض رمز JavaScript
• يمكنك تجاوز الجلب عن بُعد من خلال توفير الرمز اللازم من مصدر محلي.

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

نقاط نهاية HTTPS

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

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

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

إلغاء استرجاع لغة JavaScript عن بُعد

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

لتفعيل وضع تصحيح الأخطاء لتطبيقك، أضِف السطر التالي إلى سمة التطبيق في ملف 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);

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

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

• 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.