دليل المطوِّرين في Protected Audience API

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

تقديم ملاحظات

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

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

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

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

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

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

قبل البدء

قبل البدء، يُرجى إكمال الخطوات التالية:

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

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

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. تضمين إذن "ACCESS_ADSERVICES_CUSTOM_AUDIENCE" في تطبيقك البيان:

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

5. الإشارة إلى إعداد خدمات إعلانية في عنصر <application> في في بيان التطبيق:

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

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

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

7. تفرض واجهة برمجة التطبيقات Ad Selection API حدودًا تلقائيًا على الحد الأقصى من الذاكرة الذي يتم تحديده من خلال أحد المزادات أو مرات الظهور البرنامج النصي تخصيصه. تتطلّب ميزة الحدّ من الذاكرة توفّر إصدار WebView. 105.0.5195.58 أو أعلى. تفرض المنصة فحصًا للإصدار وتطلب يتعذّر تنفيذ واجهات برمجة التطبيقات 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 الأخرى.
• بيانات عروض الأسعار الموثوق بها: عنوان 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();

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

تستخدم طريقة 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) المصمم مسبقًا.
• المشترون ضمن شرائح الجمهور المخصّصة: قائمة كاملة بمعرّفات شبكات الإعلانات للمشترين التي تسمح للبائع بالمشاركة في عملية اختيار الإعلانات. تتوافق معرّفات المشترين مع CustomAudience.getBuyer() من والجماهير المخصّصة المشارِكة

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

• إشارات اختيار الإعلانات: كائن JSON، تم تحديده كسلسلة ويحتوي على الإشارات التي سيستهلكها منطق عروض أسعار المشترين الذي تم جلبه من 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، وعند هذه المرحلة تعمل كما هو الحال في إعلانات الأجهزة، بما في ذلك الأهلية لتصفية الإعلانات السلبية. بمجرد اكتمل مزاد يستخدم Protected Audience API. يُرجى استدعاء 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(). عرض الأحداث هي مرئية لجميع الإعلانات التي تنتمي إلى وسيط عرض الطلب (DSP) معيّن، ولا تقتصر على الإعلانات في جمهور مخصّص.
• النقرة: يتم استدعاء الحدث من خلال المتصل على الجهاز (SSP أو MMP) في نقطة معيّنة الرمز الذي يختاره باستخدام استدعاء إلى updateAdCounterHistogram(). أحداث النقر ستكون مرئية لجميع الإعلانات التي تنتمي إلى مزوّد خدمة DSP معيّن، ولا تقتصر على الإعلانات في الجمهور المخصّص نفسه

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 الرجوع إلى الأقسام المتعلقة بكيفية اختيار الإعلانات للمزادات على الجهاز فقط أو لمزادات B&A. اتّبع كيفية الإبلاغ عن الإعلان مرات الظهور (باتباع إعداد تقارير مرات الظهور لـ SSP واحد الإعلام.

شبكة التوسّط

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

تعد شبكات التوسط مسؤولة عن إدارة سلسلة التوسط ووضع أنفسهم في سلسلة التوسط. يتناول القسم التالي كيفية إعداد وتنفيذ هذه العملية.

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

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

وضع الشبكة في سلسلة التوسط

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

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

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

إنشاء AdSelectionFromResultsConfig

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

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

يمكن لموفّري خدمة المبيعات (SSP) استخدام مثال رمز حزمة تطوير البرامج (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 reportResult()، التي يُتوقع أن تعرض عنوان URL لإعداد تقارير مرات ظهور البائع.

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

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

إعداد تقارير مرات الظهور بأفضل جهد

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

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

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

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

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

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri
    registerAdBeacon("click", clickUri)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

إعداد تقارير عن أحداث التفاعل

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

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

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

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

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

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

إخراج:

• 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(
  interaction_key,
  reporting_uri
)

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

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

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

تمنح معرفات الموارد المنتظمة (URI) المصممة مسبقًا تقنيات الإعلانات القدرة على تعيين دوال 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

إنّ معرّف الموارد المنتظم (URI) الذي تم إنشاؤه مسبقًا في waterfall-mediation-truncation يوفّر ملفات JavaScript التي تنفِّذ منطق اقتطاع توسّط العرض الإعلاني بدون انقطاع حيث يتم عرض JavaScript إعلان الطرف الأول إذا كانت قيمة bid أعلى من bid floor أو مساويًا لها تُرجع null.

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

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

الاستخدام

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

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

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

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

<application
  android:debuggable="true">

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

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

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

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

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

وظائف الاختبار

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

القيود

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

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

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