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

معاينة المطوِّر إصدار تجريبي

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

---

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

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

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

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

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

يوضِّح هذا الدليل كيفية استخدام Protected Audience API على Android لإجراء ما يلي:

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

قبل البدء

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

1. إعداد بيئة تطوير "مبادرة حماية الخصوصية" على Android
2. يمكنك إما تثبيت صورة نظام على جهاز متوافق أو إعداد محاكي يتيح استخدام "مبادرة حماية الخصوصية" على 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 تلقائيًا حدودًا على الحدّ الأقصى من مساحة الذاكرة التي يمكن أن يخصّصها النص البرمجي للمزاد أو إعداد تقارير مرّات الظهور. تتطلب ميزة تقييد الذاكرة توفّر الإصدار 105.0.5195.58 أو إصدارًا أحدث من WebView. تنفّذ المنصة فحصًا للإصدار، ويتعذّر على واجهات برمجة التطبيقات selectAds وreportImpression تنفيذ الطلبات في حال عدم استيفاء ذلك. هناك خياران لإعداد هذا الإجراء:

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

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

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

الانضمام إلى جمهور مخصّص

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

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

Kotlin

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)

Java

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.
• بيانات عروض الأسعار الموثوق بها: عنوان URL يستخدم HTTPS وقائمة بالسلاسل المستخدَمة أثناء عملية اختيار الإعلانات التي تجلب إشارات عروض الأسعار من خدمة مفتاح/قيمة موثوق بها.
• الإعلانات: قائمة من عناصر AdData المقابلة للإعلانات التي تشارك في اختيار الإعلانات. يتكوّن كل عنصر AdData من:
  • عنوان URL للعرض: عنوان URL يستخدم HTTPS يتم طلبه لعرض الإعلان النهائي.
  • البيانات الوصفية: عنصر JSON متسلسل كسلسلة تحتوي على معلومات لكي يستخدمها منطق عروض أسعار المشترين أثناء عملية اختيار الإعلان.
  • فلاتر الإعلانات: فئة تحتوي على جميع المعلومات اللازمة لفلترة الإعلانات لتثبيت التطبيقات وتحديد عدد مرات الظهور أثناء اختيار الإعلان.

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

في ما يلي مثال على إنشاء مثيل لكائن CustomAudience:

Kotlin

// 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()

Java

// 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();

التعامل مع نتائج JoinCustom Audience()

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

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

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

Kotlin

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)
    }
};

Java

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 ذات الصلة.

Kotlin

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)

Java

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 ذات الصلة.

Kotlin

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
)

Java

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() AdServicesException مع السلوكيات التالية:

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

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

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

لنشر الإعلانات السياقية في التطبيق، يحتاج التطبيق المستهدَف إلى إنشاء عنصر ContextualAds:

Kotlin

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

Java

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

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

Kotlin

// 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)

Java

// 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);

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

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

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

Kotlin

//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)
    }
  })

Java

//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 لديها بمعلومات عن الإعلانات ذات الصلة بالتطبيقات التي يريدون تصفيتها:

Kotlin

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

Java

// 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 جديد:

Kotlin

// 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()

Java

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

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

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

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

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

Kotlin

// 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()

Java

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

Kotlin

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

Java

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

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

Kotlin

// 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()

Java

// 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) استدعاء أحداث النقر أو المشاهدة أو مرات الظهور الضرورية.

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

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

فلترة الإعلانات حسب المحتوى بدون استدعاءات الشبكة

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

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

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

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

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

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

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

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

شبكة التوسّط

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

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

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

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

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

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

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

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

إنشاء AdSelectionFromResultsConfig

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

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

Kotlin

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)
}

Java

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() للشبكة التابعة لجهة خارجية في المجموعة الأولى.

Kotlin

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)

Java

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. وإذا لم يتم العثور على فائز من السلسلة، يجب عرض إعلان الطرف الأول.

Kotlin

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)
}

Java

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 ذات الصلة.

Java

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);

Kotlin

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

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

ملاحظة:

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

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

• يشير رمز معاودة الاتصال onResult() إلى أنّ طلب التفاعل مع التقرير صالح.
• تشير معاودة الاتصال بـ onError() إلى الحالات المحتملة التالية:
  • إذا تم إجراء المكالمة أثناء تشغيل التطبيق في الخلفية، يتم عرض IllegalStateException مع وصف حالة الخطأ.
  • إذا تم تقييد العميل من طلب الرقم reportInteraction()، يتم عرض LimitExceededException.
  • إذا لم تكن الحزمة مسجَّلة لاستدعاء واجهات برمجة التطبيقات Privacy Preserve API، سيتم عرض الخطأ 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()

CreateBid()

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 هما وقت تفعيل الجمهور المخصّص وانتهاء صلاحيته، ويتم التعبير عنه بالثواني منذ حقبة يونكس.
  • 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()

ملاحظة: تتوفّر هذه المعلومات من خلال نظام Android الأساسي ويجب ألّا تتّبعها تكنولوجيا الإعلان.

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()، والذي تتم مقارنتها بإعلان حزمة تطوير البرامج (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">

ملاحظة: يُرجى إزالة 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 ذي الصلة.

Kotlin

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)

Java

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 ذي الصلة.

Kotlin

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

Java

// 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 ذي الصلة.

Kotlin

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)

Java

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 ذات الصلة.

Kotlin

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

Java

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

المكوِّن	وصف الحد	حد القيمة
الجمهور المخصّص (CA)	الحدّ الأقصى لعدد الإعلانات لكل مرجع تصديق	100
	الحد الأقصى لعدد مراجع التصديق لكل تطبيق	1,000
	الحدّ الأقصى لعدد التطبيقات التي يمكنها إنشاء مرجع تصديق	1,000
	الحد الأقصى للتأخير في وقت تفعيل مرجع التصديق من وقت إنشائه	60 يومًا
	الحد الأقصى لوقت انتهاء صلاحية مرجع التصديق من وقت تفعيله	60 يومًا
	الحد الأقصى لعدد مراجع التصديق على الجهاز	4,000
	الحد الأقصى لحجم اسم مرجع التصديق	200 بايت
	الحد الأقصى لحجم معرِّف الموارد المنتظم (URI) للاسترجاع اليومي	400 بايت
	الحد الأقصى لحجم معرِّف الموارد المنتظم (URI) لمنطق عروض الأسعار	400 بايت
	الحد الأقصى لحجم بيانات عروض الأسعار الموثوق بها	10 كيلوبايت
	الحد الأقصى لحجم إشارات عروض أسعار المستخدم	10 كيلوبايت
	الحد الأقصى لسعر المكالمات لـ leaveCustomAudience لكل مشترٍ	1 في الثانية
	الحد الأقصى لسعر المكالمات لـ joinCustomAudience لكل مشترٍ	1 في الثانية
جلب المحتوى في الخلفية في كاليفورنيا	انتهت مهلة الاتصال	‫٥ ثوانٍ
	مهلة قراءة HTTP	‫٣٠ ثانية
	الحد الأقصى لإجمالي حجم التنزيل	10 كيلوبايت
	الحد الأقصى لمدة تكرار الاسترجاع	5 دقائق
	تم تعديل الحد الأقصى لعدد مراجع التصديق لكل مهمة.	1,000
اختيار الإعلان	الحدّ الأقصى لعدد المشترين	يُحدَّد لاحقًا
	الحد الأقصى لعدد مراجع التصديق لكل مشترٍ	يُحدَّد لاحقًا
	الحد الأقصى لعدد الإعلانات في المزاد	يُحدَّد لاحقًا
	مهلة الاتصال المبدئية	‫٥ ثوانٍ
	انتهت مهلة قراءة الاتصال	‫٥ ثوانٍ
	الحد الأقصى لوقت التنفيذ لإجمالي AdSelection	10 ثوانٍ
	الحد الأقصى لوقت تنفيذ عرض الأسعار لكل مرجع تصديق في AdSelection	5 ثوانٍ
	الحدّ الأقصى لمدة تنفيذ التسجيل في AdSelection	5 ثوانٍ
	الحد الأقصى لوقت التنفيذ لكل مشترٍ في AdSelection	يُحدَّد لاحقًا
	الحد الأقصى لحجم إشارات اختيار الإعلانات/البائع/لكل مشترٍ	يُحدَّد لاحقًا
	الحد الأقصى لحجم النصوص البرمجية للبائع/المشتري	يُحدَّد لاحقًا
	الحد الأقصى لمعدل المكالمات لـ selectAds	1 QPS
إعداد تقارير مرات الظهور	الحد الأدنى من الوقت الذي تستغرقه إزالة اختيار الإعلان من الثبات	‫24 ساعة
	الحد الأقصى لعدد اختيارات الإعلانات للتخزين	يُحدَّد لاحقًا
	الحد الأقصى لحجم عنوان URL الخاص بناتج إعداد التقارير	يُحدَّد لاحقًا
	الحد الأقصى للوقت لإعداد تقارير مرات الظهور	يُحدَّد لاحقًا
	الحد الأقصى لعدد عمليات إعادة المحاولة لمكالمات الإشعارات	يُحدَّد لاحقًا
	انتهت المهلة المحددة للاتصال	‫٥ ثوانٍ
	الحد الأقصى لوقت التنفيذ الإجمالي لـ reportImpression	ثانيتان
	الحد الأقصى لمعدل المكالمات لـ reportImpressions	1 QPS
إعداد تقارير الأحداث	الحد الأقصى لعدد أجهزة المرشد لكل مشترٍ في كل مزاد	10
	الحد الأقصى لعدد أجهزة المرشد لكل بائع في كل مزاد	10
	الحد الأقصى لحجم مفتاح الحدث	40 بايت
	الحد الأقصى لحجم بيانات الأحداث	64 كيلوبايت
الإعلانات	الحد الأقصى لحجم قائمة الإعلانات	10 كيلوبايت والتي يشاركها جميع AdData في مرجع تصديق واحد للسياق
URLs	الحد الأقصى لطول أي سلسلة عنوان URL يتم أخذها كإدخال	يُحدَّد لاحقًا
JavaScript	الحد الأقصى لمدة التنفيذ	ثانية واحدة لتقديم عروض الأسعار والنتائج في تقارير مرات الظهور
	الحد الأقصى للذاكرة المستخدمة	10 ميغابيات

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

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