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

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

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

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

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

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

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

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

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

6. أضِف مرجعًا إلى إعدادات خدمات الإعلانات في العنصر <application> من ملف البيان:

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

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

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

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

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

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لعرض الإعلانات بدون إجراء طلبات من الشبكة، اتّبِع الخطوات التالية:

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

3. أنشئ عنصر AdSelectionConfig يتضمّن ما يلي:

   1. قائمة فارغة بالمشترين
   2. معرّف موارد موحّد (URI) مُنشأ مسبقًا لاختيار أعلى عرض سعر
   3. الإعلانات السياقية
   4. معرّف موارد منتظم (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 لإعداد التقارير أثناء استخدام معرّفات الموارد الموحّدة (URI) المُنشأة مسبقًا

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

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

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

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

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

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

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

شبكة التوسّط

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

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

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

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

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

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

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

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

إنشاء عنصر AdSelectionFromOutcomesConfig

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

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

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

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

    return adSelectionClient.selectAds(config){}
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

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

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

إعداد تقارير عن مرّة ظهور واحدة على منصة عرض

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

يمكن لمنصّات عرض الإعلانات (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 الخاص بمنطق اتّخاذ القرار لدى البائع.
• استدعِ دالة JavaScript reportResult() التي من المتوقّع أن تعرض عنوان URL لإعداد تقارير مرات الظهور الخاصّة بالبائع.

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

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

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

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

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

توفّر Protected Audience إمكانية إعداد تقارير عن تفاعلات أكثر تفصيلاً مع إعلان معروض. ويمكن أن يشمل ذلك تفاعلات مثل وقت المشاهدة أو النقرات أو التمرير فوق العناصر أو أي مقياس آخر مفيد يمكن جمعه. تتطلّب عملية تلقّي هذه التقارير خطوتَين. أولاً، على المشترين والبائعين التسجيل لتلقّي هذه التقارير في 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.
  • إذا لم تكن الحزمة مسجّلة لاستخدام واجهات Privacy Preserving APIs، سيتم عرض SecurityException().
  • إذا كان التطبيق الذي يبلغ عن التفاعلات مختلفًا عن التطبيق الذي طلب selectAds()، سيتم عرض IllegalStateException.
• إذا لم يوافق المستخدم على تفعيل واجهات Privacy Sandbox API، سيتعذّر تنفيذ الطلب بدون إظهار أي رسالة خطأ.

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

تُصدر واجهة برمجة التطبيقات الخاصة بتفاعلات التقارير طلبات HTTPS POST إلى نقاط النهاية التي توفّرها منصة العرض ومنصة الشراء الفائزة. ستطابق Protected Audience مفاتيح التفاعل مع معرّفات الموارد الموحّدة (URI) المُعلن عنها في JavaScript لإعداد التقارير، وسترسل طلب POST إلى كل نقطة نهاية لكل تفاعل يتم تسجيله. Content-Type الطلب هو نص عادي، أما النص فيكون بيانات التفاعل.

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

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

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

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

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

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

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

  where:

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

النتيجة:

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

scoreAd()

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

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

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

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

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

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

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

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

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

إخراج:

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

selectOutcome()

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

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

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

إخراج:

• ‫status: 0 للنجاح، قيمة غير صفرية للفشل
• ‫result: إحدى النتائج التي تم تمريرها أو لا تتضمّن قيمة

reportResult()

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

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

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

إخراج:

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

reportWin()

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

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

• ad_selection_signals, per_buyer_signals: يُرجى الاطّلاع على المستندات الخاصة بـ scoreAd
• ‫signals_for_buyer: كائن JSON تم إرجاعه بواسطة reportResult
• contextual_signals, custom_audience_signals: يُرجى الاطّلاع على المستندات الخاصة بـ generateBid

إخراج:

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

registerAdBeacon()

function registerAdBeacon(
  beacons
)

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

• ‫beacons: عنصر يحتوي على أزواج المفتاح-القيمة لمفاتيح التفاعل ومعرّفات الموارد المنتظمة الخاصة بإعداد التقارير. التنسيق هو:

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

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

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

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

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

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

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

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

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

يتم عرض الخطأ IllegalArgumentException في الحالات التالية:

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

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

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

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

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

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

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

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

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

الاستخدام

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

`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() والذي تتمّ مقارنته بالإعلان في حزمة 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.