Protected Audience API डेवलपर गाइड

Android पर Privacy Sandbox के दस्तावेज़ को पढ़ते समय, डेवलपर के लिए झलक या बीटा बटन का इस्तेमाल करके, उस प्रोग्राम वर्शन को चुनें जिसका इस्तेमाल किया जा रहा है. ऐसा इसलिए, क्योंकि निर्देश अलग-अलग हो सकते हैं.


Android पर Protected Audience API (पहले इसे FLEDGE के नाम से जाना जाता था) में, Custom Audience API और Ad Selection API शामिल हैं. विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म और विज्ञापन देने वाले, इन एपीआई का इस्तेमाल करके उपयोगकर्ताओं के हिसाब से विज्ञापन दिखा सकते हैं. ये विज्ञापन, उपयोगकर्ता के ऐप्लिकेशन में पहले के अनुभव के आधार पर दिखाए जाते हैं. इनसे, सभी ऐप्लिकेशन में आइडेंटिफ़ायर शेयर करने पर पाबंदी लगती है. साथ ही, उपयोगकर्ता के ऐप्लिकेशन इंटरैक्शन की जानकारी को तीसरे पक्षों के साथ शेयर करने पर भी पाबंदी लगती है.

कस्टम ऑडियंस एपीआई, "कस्टम ऑडियंस" के एब्स्ट्रैक्शन पर आधारित है. यह एक ऐसा ग्रुप होता है जिसमें एक जैसे इंटेंट वाले उपयोगकर्ता शामिल होते हैं. विज्ञापन देने वाला व्यक्ति या कंपनी, किसी उपयोगकर्ता को कस्टम ऑडियंस के साथ रजिस्टर कर सकती है और उससे काम के विज्ञापन जोड़ सकती है. इस जानकारी को डिवाइस पर सेव किया जाता है. इसका इस्तेमाल, विज्ञापन देने वाले की बिड, विज्ञापन फ़िल्टर करने, और विज्ञापन रेंडर करने के लिए किया जा सकता है.

विज्ञापन चुनने वाला API एक फ़्रेमवर्क उपलब्ध कराता है. इसकी मदद से, एक से ज़्यादा डेवलपर, कस्टम ऑडियंस के लिए स्थानीय तौर पर नीलामी चला सकते हैं. ऐसा करने के लिए, सिस्टम कस्टम ऑडियंस से जुड़े काम के विज्ञापनों को ध्यान में रखता है. साथ ही, विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म से डिवाइस पर दिखाए जाने वाले विज्ञापनों पर अतिरिक्त प्रोसेसिंग करता है.

विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म, उपयोगकर्ता की निजता बनाए रखते हुए रीमार्केटिंग लागू करने के लिए, इन एपीआई को इंटिग्रेट कर सकते हैं. आने वाले समय में, ऐप्लिकेशन इंस्टॉल करने के लिए बढ़ावा देने वाले विज्ञापनों के साथ-साथ, अन्य इस्तेमाल के उदाहरणों के लिए भी इस सुविधा का इस्तेमाल किया जा सकेगा. डिज़ाइन के प्रस्ताव में, Android पर Protected Audience API के बारे में ज़्यादा जानें.

इस गाइड में, Android पर Protected Audience API के साथ काम करने का तरीका बताया गया है, ताकि ये काम किए जा सकें:

  1. कस्टम ऑडियंस मैनेज करना
  2. किसी डिवाइस पर विज्ञापन चुनने की सुविधा सेट अप करना और उसे चलाना
  3. विज्ञापन इंप्रेशन की शिकायत करना

शुरू करने से पहले

शुरू करने से पहले, ये काम पूरे करें:

  1. Android पर Privacy Sandbox के लिए, अपना डेवलपमेंट एनवायरमेंट सेट अप करें.
  2. इस सुविधा के साथ काम करने वाले डिवाइस पर सिस्टम इमेज इंस्टॉल करें या ऐसा एमुलेटर सेट अप करें जिसमें Android पर Privacy Sandbox की सुविधा काम करती हो.
  3. टर्मिनल में, adb कमांड की मदद से Protected Audience API को ऐक्सेस करने की सुविधा चालू करें. यह एपीआई डिफ़ॉल्ट रूप से बंद रहता है.

      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. अपनी मेनिफ़ेस्ट फ़ाइल में रेफ़र किए गए विज्ञापन सेवाओं के एक्सएमएल रिसॉर्स की जानकारी दें, जैसे कि 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 या इसके बाद का वर्शन ज़रूरी है. प्लैटफ़ॉर्म, वर्शन की जांच करता है. अगर यह जांच पूरी नहीं होती है, तो selectAds और reportImpression एपीआई के कॉल पूरा नहीं होते. इसे सेट अप करने के दो विकल्प हैं:

    • पहला विकल्प: इस जांच को बंद करने के लिए, adb का यह कमांड चलाएं:

      adb device_config put fledge_js_isolate_enforce_max_heap_size false
      
    • दूसरा विकल्प: Google Play Store से WebView Beta इंस्टॉल करें. यह वर्शन, पहले बताए गए वर्शन के बराबर या उससे ज़्यादा होना चाहिए.

कस्टम ऑडियंस में शामिल होना

कस्टम ऑडियंस, विज्ञापन देने वाले ऐप्लिकेशन के हिसाब से, एक जैसे इंटेंट या दिलचस्पी वाले उपयोगकर्ताओं के ग्रुप को दिखाती है. कोई ऐप्लिकेशन या SDK टूल, किसी खास ऑडियंस को दिखाने के लिए कस्टम ऑडियंस का इस्तेमाल कर सकता है. जैसे, कोई व्यक्ति जिसने शॉपिंग कार्ट में आइटम छोड़े हैं. किसी कस्टम ऑडियंस को असिंक्रोनस तरीके से बनाने या उसमें शामिल होने के लिए, यह तरीका अपनाएं:

  1. CustomAudienceManager ऑब्जेक्ट को शुरू करें.
  2. खरीदार के पैकेज और काम का नाम जैसे अहम पैरामीटर की जानकारी देकर, CustomAudience ऑब्जेक्ट बनाएं. इसके बाद, CustomAudience ऑब्जेक्ट की मदद से, JoinCustomAudienceRequest ऑब्जेक्ट को शुरू करें.
  3. JoinCustomAudienceRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, असाइनोक्रोनस joinCustomAudience() को कॉल करें.

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: कस्टम ऑडियंस के लिए कोई भी नाम या आइडेंटिफ़ायर.

CustomAudience के किसी दूसरे इंस्टेंस के साथ joinCustomAudience() को बार-बार कॉल करने पर, मिलते-जुलते owner, buyer और name पैरामीटर के साथ, किसी भी मौजूदा CustomAudience को अपडेट किया जाता है. निजता को बनाए रखने के लिए, एपीआई के नतीजे में "बनाने" और "अपडेट करने" के बीच कोई फ़र्क़ नहीं किया जाता.

इसके अलावा, CustomAudience को इन ज़रूरी पैरामीटर के साथ बनाया जाना चाहिए:

  • रोज़ अपडेट होने वाला यूआरएल: यह एक एचटीटीपीएस यूआरएल है. इसकी क्वेरी हर रोज़ बैकग्राउंड में की जाती है, ताकि कस्टम ऑडियंस के उपयोगकर्ता बिडिंग सिग्नल, भरोसेमंद बिडिंग डेटा को अपडेट किया जा सके. साथ ही, विज्ञापनों के लिए यूआरएल और मेटाडेटा को रेंडर किया जा सके.
  • बिडिंग लॉजिक यूआरएल: विज्ञापन चुनने के दौरान, बिडिंग लॉजिक का JavaScript फ़ेच करने के लिए, एचटीटीपीएस यूआरएल से क्वेरी की जाती है. इस JavaScript में ज़रूरी फ़ंक्शन हस्ताक्षर देखें.
  • विज्ञापन रेंडर आईडी: यह एक ऐसा आईडी होता है जिसे खरीदार की विज्ञापन टेक्नोलॉजी सेट करती है. यह B&A के लिए पेलोड जनरेट करने के लिए ऑप्टिमाइज़ेशन है.

CustomAudience ऑब्जेक्ट के लिए, वैकल्पिक पैरामीटर में ये शामिल हो सकते हैं:

  • चालू होने का समय: कस्टम ऑडियंस, विज्ञापन चुनने और रोज़ के अपडेट में सिर्फ़ तब हिस्सा ले सकती है, जब वह चालू हो. उदाहरण के लिए, यह किसी ऐप्लिकेशन के ऐसे उपयोगकर्ताओं को फिर से जोड़ने के लिए मददगार हो सकता है जो ऐप्लिकेशन का इस्तेमाल करना बंद कर चुके हैं.
  • खत्म होने का समय: वह समय जब कस्टम ऑडियंस को डिवाइस से हटा दिया जाएगा.
  • उपयोगकर्ता के बिडिंग सिग्नल: उपयोगकर्ता के सिग्नल वाली JSON स्ट्रिंग, जैसे कि उपयोगकर्ता की पसंदीदा स्थानीय भाषा. विज्ञापन चुनने की प्रोसेस के दौरान बिड जनरेट करने के लिए, बिडिंग लॉजिक JavaScript इनका इस्तेमाल करता है. इस फ़ॉर्मैट की मदद से, विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म, सभी प्लैटफ़ॉर्म पर कोड का फिर से इस्तेमाल कर सकते हैं. साथ ही, JavaScript फ़ंक्शन का इस्तेमाल करना आसान हो जाता है.
  • भरोसेमंद बिडिंग डेटा: विज्ञापन चुनने की प्रोसेस के दौरान इस्तेमाल किए जाने वाले एचटीटीपीएस यूआरएल और स्ट्रिंग की सूची. यह सूची, भरोसेमंद कुंजी/वैल्यू सेवा से बिडिंग सिग्नल फ़ेच करती है.
  • विज्ञापन: विज्ञापन चुनने की प्रोसेस में हिस्सा लेने वाले विज्ञापनों से जुड़े AdData ऑब्जेक्ट की सूची. हर AdData ऑब्जेक्ट में ये शामिल होते हैं:
    • रेंडर यूआरएल: यह एक एचटीटीपीएस यूआरएल होता है. फ़ाइनल विज्ञापन को रेंडर करने के लिए, इसकी क्वेरी की जाती है.
    • मेटाडेटा: स्ट्रिंग के तौर पर सीरियलाइज़ किया गया JSON ऑब्जेक्ट, जिसमें विज्ञापन चुनने की प्रोसेस के दौरान, बिडिंग के लिए खरीदार के लॉजिक का इस्तेमाल करने के लिए जानकारी होती है.
    • विज्ञापन फ़िल्टर: यह एक ऐसी क्लास है जिसमें विज्ञापन चुनने के दौरान, ऐप्लिकेशन इंस्टॉल करने के लिए विज्ञापन फ़िल्टर करने और फ़्रीक्वेंसी कैपिंग से जुड़ी सभी ज़रूरी जानकारी होती है.

यहां 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();

joinCustomAudience() के नतीजों को मैनेज करना

एपीआई कॉल के नतीजे का सिग्नल देने के लिए, असाइनोक्रोनस 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. कस्टम ऑडियंस के buyer और name की मदद से, LeaveCustomAudienceRequest को शुरू करें. इन इनपुट फ़ील्ड के बारे में ज़्यादा जानने के लिए, "कस्टम ऑडियंस में शामिल हों" लेख पढ़ें.
  3. LeaveCustomAudienceRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एक साथ काम करने वाले leaveCustomAudience() तरीके को कॉल करें.

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() callback को कॉल किया जाता है. भले ही, मैच करने वाली कस्टम ऑडियंस को हटाया गया हो या नहीं.

विज्ञापन चुनने की सुविधा चलाना

विज्ञापन चुनने के लिए Protected Audience API का इस्तेमाल करने के लिए, selectAds() तरीका कॉल करें:

  1. AdSelectionManager ऑब्जेक्ट को शुरू करना.
  2. AdSelectionConfig ऑब्जेक्ट बनाएं.
  3. AdSelectionConfig ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एक साथ काम करने वाले selectAds() तरीके को कॉल करें.

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 इनपुट की ज़रूरत होती है. इसमें, आपको ये ज़रूरी पैरामीटर बताने होंगे:

  • सेलर: विज्ञापन चुनने की प्रोसेस शुरू करने वाले सेलर विज्ञापन नेटवर्क का आइडेंटिफ़ायर.
  • फ़ैसला लेने का लॉजिक यूआरएल: यह एक एचटीटीपीएस यूआरएल है, जिससे सेलर के विज्ञापन नेटवर्क का JavaScript लॉजिक पाने के लिए क्वेरी की जाती है.
    • एचटीटीपीएस यूआरएल: सेलर के विज्ञापन नेटवर्क का JavaScript लॉजिक पाने के लिए क्वेरी की गई. ज़रूरी फ़ंक्शन हस्ताक्षर देखें.
    • पहले से बना यूआरआई: यह FLEDGE के विज्ञापन चुनने के फ़ॉर्मैट का पालन करता है. अगर पहले से तैयार किया गया यूआरआई अमान्य या गलत है, तो IllegalArgumentException गड़बड़ी का मैसेज दिखाता है.
  • कस्टम ऑडियंस के खरीदार: विज्ञापन नेटवर्क कंपनियों के लिए आइडेंटिफ़ायर की पूरी सूची, जिन्हें विज्ञापन चुनने की प्रोसेस में हिस्सा लेने की अनुमति सेलर ने दी है. ये खरीदार आइडेंटिफ़ायर, हिस्सा लेने वाली CustomAudience.getBuyer() कस्टम ऑडियंस से जुड़े होते हैं.

विज्ञापन चुनने के लिए, ज़्यादा कस्टमाइज़ेशन के लिए, नीचे दिए गए पैरामीटर का इस्तेमाल किया जा सकता है:

  • विज्ञापन चुनने के सिग्नल: यह एक JSON ऑब्जेक्ट है, जिसे स्ट्रिंग के तौर पर सीरियलाइज़ किया गया है. इसमें CustomAudience.getBiddingLogicUrl() से फ़ेच किए गए, बिडिंग लॉजिक JavaScript के ज़रिए इस्तेमाल किए जाने वाले सिग्नल शामिल होते हैं.
  • सेलर सिग्नल: यह एक JSON ऑब्जेक्ट है, जिसे स्ट्रिंग के तौर पर सीरियलाइज़ किया गया है. इसमें ऐसे सिग्नल होते हैं जिनका इस्तेमाल, सेलर के फ़ेच किए गए JavaScript फ़ैसले के लॉजिक में किया जाता है. यह लॉजिक, AdSelectionConfig.getDecisionLogicUrl() से फ़ेच किया जाता है.
  • हर खरीदार के सिग्नल: यह JSON ऑब्जेक्ट का एक मैप है, जिसे स्ट्रिंग के तौर पर सीरियलाइज़ किया गया है. इसमें ऐसे सिग्नल होते हैं जिन्हें CustomAudience.getBiddingLogicUrl() से फ़ेच किए गए, खरीदारों के बिडिंग लॉजिक JavaScript के ज़रिए इस्तेमाल किया जाता है. इन सिग्नल की पहचान, हिस्सा लेने वाली कस्टम ऑडियंस के खरीदार फ़ील्ड से की जाती है.
  • कॉन्टेक्स्ट के हिसाब से विज्ञापन: विज्ञापन के लिए संभावित विकल्पों का ऐसा कलेक्शन जो सुरक्षित ऑडियंस नीलामी के बाहर होने वाली नीलामी के दौरान, सीधे तौर पर खरीदारों से इकट्ठा किया जाता है.

कोई विज्ञापन चुनने के बाद, नतीजे, बिड, और सिग्नल को रिपोर्टिंग के लिए अंदरूनी तौर पर सेव किया जाता है. OutcomeReceiver.onResult() कॉलबैक, एक ऐसा AdSelectionOutcome दिखाता है जिसमें ये चीज़ें शामिल होती हैं:

  • AdData.getRenderUrl() से मिला, विज्ञापन दिखाने के लिए रेंडर किया गया यूआरएल.
  • डिवाइस के उपयोगकर्ता के लिए यूनीक विज्ञापन चुनने वाला आईडी. इस आईडी का इस्तेमाल, विज्ञापन इंप्रेशन की रिपोर्टिंग के लिए किया जाता है.

अगर अमान्य आर्ग्युमेंट, टाइम आउट या ज़्यादा संसाधन खर्च होने जैसी वजहों से विज्ञापन का चयन पूरा नहीं हो पाता है, तो OutcomeReceiver.onError() कॉलबैक, इन तरीकों के साथ AdServicesException दिखाता है:

  • अगर विज्ञापन चुनने की प्रोसेस अमान्य आर्ग्युमेंट के साथ शुरू की जाती है, तो AdServicesException, IllegalArgumentException को वजह के तौर पर दिखाता है.
  • अन्य सभी गड़बड़ियों के लिए, AdServicesException को गड़बड़ी की वजह के तौर पर IllegalStateException के साथ दिखाया जाता है.

कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाना

Protected Audience, Protected Auction में कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखा सकता है. कॉन्टेक्स्ट के हिसाब से विज्ञापनों को विज्ञापन टेक्नोलॉजी सर्वर पर चुना जाना चाहिए और उन्हें डिवाइस पर, Protected Audience API के बाहर दिखाया जाना चाहिए. इसके बाद, AdSelectionConfig का इस्तेमाल करके, ऑक्शन में कॉन्टेक्स्ट विज्ञापन शामिल किए जा सकते हैं. इस दौरान, ये विज्ञापन ठीक वैसे ही काम करते हैं जैसे डिवाइस पर दिखने वाले विज्ञापन. इनमें, नेगेटिव विज्ञापन फ़िल्टर करने की ज़रूरी शर्तें भी शामिल हैं. सुरक्षित ऑडियंस की नीलामी पूरी होने के बाद, आपको reportImpression() को शुरू करना होगा. यह किसी डिवाइस पर विज्ञापन दिखाने के लिए, इंप्रेशन रिपोर्टिंग के उसी पैटर्न में, विज्ञापन दिखाने के लिए चुने गए कॉन्टेक्स्ट विज्ञापन में reportWin() को कॉल करता है. हर संदर्भ के हिसाब से दिखाए जाने वाले विज्ञापन के लिए, खरीदार, बिड, रिपोर्टिंग लॉजिक का लिंक, रेंडर यूआरएल, और विज्ञापन मेटाडेटा की ज़रूरत होती है.

ऐप्लिकेशन में कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाने के लिए, टारगेट किए गए ऐप्लिकेशन को एक 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();

इसके बाद, AdSelectionConfig बनाते समय, ContextualAds ऑब्जेक्ट को पास किया जा सकता है:

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 से अलग, डिवाइस पर कॉल करने वाला (एसएसपी या एमएमपी) updateAdCounterHistogram() का इस्तेमाल करता है, ताकि वह अपने चुने गए कोड में, इंप्रेशन इवेंट को ट्रिगर कर सके. इंप्रेशन इवेंट, किसी डीएसपी से जुड़े सभी विज्ञापनों को दिखते हैं. ये एक ही कस्टम ऑडियंस के विज्ञापनों तक सीमित नहीं होते.
  • व्यू: डिवाइस पर मौजूद कॉलर (एसएसपी या एमएमपी), कोड में किसी ऐसे पॉइंट पर इवेंट को ट्रिगर करता है जिसे वह updateAdCounterHistogram() को कॉल करके चुनता है. व्यू इवेंट, किसी डीएसपी से जुड़े सभी विज्ञापनों को दिखते हैं. ये एक ही कस्टम ऑडियंस के विज्ञापनों तक सीमित नहीं होते.
  • क्लिक: इवेंट को डिवाइस पर मौजूद कॉलर (एसएसपी या एमएमपी) ने कोड में किसी ऐसे पॉइंट पर ट्रिगर किया है जिसे उन्होंने updateAdCounterHistogram() को कॉल करके चुना है. क्लिक इवेंट, किसी डीएसपी से जुड़े सभी विज्ञापनों को दिखते हैं. ये एक ही कस्टम ऑडियंस के विज्ञापनों तक सीमित नहीं होते.

पब्लिशर ऐप्लिकेशन में, डिवाइस पर मौजूद एसएसपी या एमएमपी, विज्ञापन इवेंट को ट्रिगर करता है. updateAdCounterHistogram() को कॉल करने पर, फ़्रीक्वेंसी कैप फ़िल्टर का काउंटर बढ़ जाता है, ताकि आने वाले समय में होने वाली नीलामियों में, किसी उपयोगकर्ता को किसी विज्ञापन के एक्सपोज़र के बारे में अप-टू-डेट जानकारी हो. विज्ञापन इवेंट के टाइप, उपयोगकर्ता की कार्रवाई से ज़बरदस्ती नहीं जुड़े होते. ये दिशा-निर्देश, कॉल करने वालों को अपने इवेंट सिस्टम को व्यवस्थित करने में मदद करने के लिए दिए जाते हैं. किसी इवेंट के समय विज्ञापन काउंटर बढ़ाने के लिए, डिवाइस पर मौजूद ऐक्टर, विज्ञापन नीलामी में जीतने वाले विज्ञापन के विज्ञापन सिलेक्शन आईडी की जानकारी देता है.

विज्ञापन काउंटर कुंजियां, 32-बिट की ऐसी पूरी संख्याएं होती हैं जिन्हें खरीदार के विज्ञापन टेक्नोलॉजी ने असाइन किया होता है. ये कुंजियां, DSP के मुताबिक विज्ञापनों के किसी सेट से जुड़ी होती हैं. विज्ञापन काउंटर की कुंजियां, सिर्फ़ किसी डीएसपी से जुड़े विज्ञापनों तक सीमित होती हैं. इसलिए, इन कुंजियों को किसी दूसरे विज्ञापन टेक्नोलॉजी के हिस्टोग्राम के साथ ओवरलैप किए बिना चुना जा सकता है. विज्ञापन काउंटर की कुंजियों का इस्तेमाल, डीएसपी के विज्ञापनों या किसी कस्टम ऑडियंस में डीएसपी के हिसाब से आइडेंटिफ़ायर बढ़ाने के लिए किया जाता है, ताकि आने वाले समय में होने वाली नीलामियों से विज्ञापनों को फ़िल्टर किया जा सके.

काउंटर बटन का इस्तेमाल करके, उन विज्ञापनों को प्राथमिकता दी जा सकती है जो किसी उपयोगकर्ता के लिए दिलचस्प हो सकते हैं. यह प्राथमिकता, किसी खरीदार की विज्ञापन टेक्नोलॉजी से दिखाए गए अन्य विज्ञापनों के साथ उपयोगकर्ता के इंटरैक्शन के आधार पर तय की जाती है. उदाहरण के लिए, किसी विज्ञापन को जीतने वाली विज्ञापन नीलामियों, व्यू, और क्लिक से ज़्यादा यूज़र ऐक्टिविटी मिली है, तो यह अनुमानित डेटा पॉइंट दिखाता है. इस बात को और बेहतर तरीके से समझने के लिए: बाएं हाथ के लिए बने गोल्फ क्लब के विज्ञापन से यह पता चल सकता है कि उपयोगकर्ता को दाएं हाथ के लिए बने क्लब में दिलचस्पी नहीं है. बाएं हाथ के लिए विज्ञापनों को असाइन किए गए काउंटर बटन के लिए सेट किया गया फ़्रीक्वेंसी कैप फ़िल्टर, दाएं हाथ के लिए विज्ञापनों को फ़िल्टर कर सकता है.

अपनी ऑक्शन में फ़्रीक्वेंसी कैपिंग का इस्तेमाल करने के लिए, आपको पहले 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();

जब कस्टम ऑडियंस में फ़्रीक्वेंसी कैप फ़िल्टर लागू किए जाते हैं, तो एसएसपी ज़रूरी क्लिक, व्यू या इंप्रेशन इवेंट को ट्रिगर कर सकता है.

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

ऐसे विज्ञापनों को नीलामी से बाहर रखा जाता है जिन्होंने पहले से सेट की गई फ़्रीक्वेंसी कैप की सीमाएं पूरी कर ली हों. डिवाइस पर होने वाली नीलामियों के लिए बिडिंग लॉजिक लागू होने से पहले और बिडिंग और नीलामी सेवाओं की नीलामियों के लिए पेलोड जनरेट होने के दौरान, फ़िल्टरिंग की जाती है. इस टूलकिट की मदद से, विज्ञापन टेक्नोलॉजी विशेषज्ञ, उपयोगकर्ताओं और कस्टम ऑडियंस में मौजूद विज्ञापनों के बीच हुए इंटरैक्शन का इस्तेमाल कर सकते हैं. इससे, विज्ञापन को ज़्यादा से ज़्यादा लोगों को दिखाने के साथ-साथ, विज्ञापन टारगेटिंग पर फ़ोकस किया जा सकता है.

नेटवर्क कॉल के बिना, कॉन्टेक्स्ट के हिसाब से विज्ञापन फ़िल्टर करना

अगर डिवाइस पर रीमार्केटिंग की कोई मांग नहीं है, तो नेटवर्क कॉल के बिना, कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाने के लिए विज्ञापन चुनने की सुविधा चालू की जा सकती है. पहले से बनाए गए यूआरआई और बिड के साथ काम के विज्ञापनों की सूची की मदद से, प्लैटफ़ॉर्म बिडिंग लॉजिक, बिडिंग सिग्नल, और स्कोरिंग सिग्नल को फिर से पाने की प्रोसेस को छोड़ सकता है. प्लैटफ़ॉर्म, सबसे ज़्यादा बिड वाले कॉन्टेक्स्ट विज्ञापन को चुनने के लिए, पहले से बनाए गए यूआरआई का इस्तेमाल करता है.

विज्ञापन टेक्नोलॉजी, विज्ञापन चुनने का ऐसा फ़्लो चला सकती हैं जिससे विज्ञापन दिखने में लगने वाले समय को कम किया जा सके. इस फ़्लो में, नेटवर्क कॉल के बिना विज्ञापन फ़िल्टर करने की सुविधा के साथ, सिर्फ़ कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाए जाते हैं. ऐसा, सिग्नल को स्कोर करने के लिए पहले से बनाए गए यूआरआई का इस्तेमाल करके किया जाता है. scoreAds को लागू करने के तरीकों की सूची के लिए, पहले से बने यूआरआई के इस्तेमाल के उदाहरण और नाम वाले सेक्शन देखें.

नेटवर्क कॉल के बिना विज्ञापन चुनने की सुविधा चलाने के लिए:

  1. विज्ञापन फ़िल्टर करने की सुविधा सेट अप करना
  2. अपने कॉन्टेक्स्ट के हिसाब से विज्ञापन बनाना
  3. इनके साथ AdSelectionConfig ऑब्जेक्ट बनाएं:

    1. खरीदारों की खाली सूची
    2. सबसे ज़्यादा बिड चुनने के लिए, पहले से बना यूआरआई
    3. कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाना
    4. स्कोरिंग सिग्नल के लिए खाली यूआरआई. खाली यूआरएल से यह पता चलता है कि आपको स्कोरिंग के लिए, भरोसेमंद सिग्नल फ़ेच करने की सुविधा का इस्तेमाल नहीं करना है:
    Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
    // Initialize AdSelectionConfig
    AdSelectionConfig adSelectionConfig =
      new AdSelectionConfig.Builder()
        .setSeller(seller)
        .setDecisionLogicUri(prebuiltURIScoringUri)
        .setCustomAudienceBuyers(Collections.emptyList())
        .setAdSelectionSignals(adSelectionSignals)
        .setSellerSignals(sellerSignals)
        .setPerBuyerSignals(perBuyerSignals)
        .setBuyerContextualAds(buyerContextualAds)
        .setTrustedScoringSignalsUri(Uri.EMPTY)
        .build();
    
  4. विज्ञापन चुनने की सुविधा चलाएं:

    adSelectionManager.selectAds(
        adSelectionConfig,
        executor,
        outcomeReceiver);
    

पहले से बनाए गए यूआरआई का इस्तेमाल करते समय, अपनी रिपोर्टिंग JavaScript को चलाना

फ़िलहाल, Privacy Sandbox प्लैटफ़ॉर्म पर, पहले से बनाए गए यूआरआई के लिए सिर्फ़ बुनियादी रिपोर्टिंग JavaScript लागू है. अगर आपको विज्ञापन चुनने में कम समय लगने के लिए, पहले से बनाए गए यूआरआई का इस्तेमाल करते हुए अपनी रिपोर्टिंग JavaScript चलानी है, तो विज्ञापन चुनने और रिपोर्टिंग के बीच DecisionLogicUri को बदला जा सकता है.

  1. पहले से बनाए गए यूआरआई का इस्तेमाल करके, कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाने के लिए, विज्ञापन चुनने की सुविधा को चलाने का तरीका
  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 टूल (3P नेटवर्क) को पहले पक्ष के 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 की जानकारी देने वाले सेक्शन देख सकती हैं. विज्ञापन इंप्रेशन को रिपोर्ट करने का तरीका जानें. इसके लिए, एक एसएसपी इंप्रेशन रिपोर्टिंग का पालन करें.

मीडिएशन नेटवर्क

तीसरे पक्ष के नेटवर्क की तरह ही, मीडिएशन नेटवर्क को selectAds और reportImpression लागू करने की ज़रूरत है. ज़्यादा जानकारी के लिए, विज्ञापन चुनने की प्रोसेस को चलाने और विज्ञापन इंप्रेशन को रिपोर्ट करने के तरीके के बारे में बताने वाले सेक्शन देखें.

मीडिएशन चेन को चलाने और खुद को मीडिएशन चेन में शामिल करने की ज़िम्मेदारी, मीडिएशन नेटवर्क की होती है. अगले सेक्शन में, इस प्रोसेस को सेट अप करने और उसे लागू करने का तरीका बताया गया है.

मीडिएशन चेन और बिड फ़्लोर वापस पाना

मीडिएशन नेटवर्क, पहले पक्ष (1P) के संदर्भ के मुताबिक विज्ञापन, मीडिएशन चेन, और तीसरे पक्ष के नेटवर्क के बिड फ़्लोर (3P) को वापस लाने के लिए ज़िम्मेदार होता है. ऐसा, मीडिएशन नेटवर्क की मदद से दिखाए जाने वाले संदर्भ के हिसाब से विज्ञापनों को वापस पाने के अनुरोध में हो सकता है. मीडिएशन चेन से यह तय होता है कि तीसरे पक्ष के नेटवर्क को कैसे दोहराया जाए. साथ ही, बिड फ़्लोर को नीलामी की प्रोसेस में adSelectionSignals के तौर पर पास किया जा सकता है.

मीडिएशन चेन में नेटवर्क प्लेसमेंट

मीडिएशन SDK टूल, 1P विज्ञापन बिड के लाइव eCPM के आधार पर, खुद को मीडिएशन चेन में डाल सकता है. Protected Audience API में, विज्ञापन बिड को छिपाया जाता है. किसी 1P विज्ञापन की बिड की तुलना, चेन में अगले 3P नेटवर्क के बिड फ़्लोर से करने के लिए, मीडिएशन SDK को AdSelectionFromOutcomesConfig का इस्तेमाल करना चाहिए. अगर 1P बिड, बिड फ़्लोर से ज़्यादा है, तो इसका मतलब है कि मीडिएशन SDK को उस 3P नेटवर्क के सामने रखा गया है.

विज्ञापन चुनने की सुविधा चलाना

पहले पक्ष (1P) के विज्ञापन कैंडिडेट को वापस पाने के लिए, मीडिएशन नेटवर्क विज्ञापन चुनने की प्रोसेस सेक्शन में दिए गए चरणों का पालन करके, डिवाइस पर होने वाली नीलामी को पूरा कर सकता है. इससे, 1P विज्ञापन कैंडिडेट, बिड, और AdSelectionId जनरेट होता है. इसका इस्तेमाल मीडिएशन प्रोसेस में किया जाता है.

AdSelectionFromOutcomesConfig बनाएं

AdSelectionFromOutcomesConfig की मदद से, मीडिएशन नेटवर्क, AdSelectionIds (पिछली नीलामियों के नतीजे), विज्ञापन चुनने के सिग्नल, और यूआरएल की सूची पास कर सकता है. इससे, कई विज्ञापनों में से किसी एक को चुनने वाला JavaScript फ़ेच किया जा सकता है. AdSelectionIds की सूची के साथ-साथ उनकी बिड और सिग्नल, JavaScript को भेजे जाते हैं. अगर यह बिड फ़्लोर से ज़्यादा है, तो यह AdSelectionIds में से किसी एक को दिखा सकता है. अगर मीडिएशन चेन जारी रहनी चाहिए, तो यह कोई भी नहीं दिखा सकता.

मीडिएशन नेटवर्क, पिछले सेक्शन के 1P AdSelectionId और 3P नेटवर्क के बिड फ़्लोर का इस्तेमाल करके AdSelectionFromOutcomesConfig बनाते हैं. मीडिएशन चेन के हर चरण के लिए, एक नया 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: 1P विज्ञापन के लिए, पिछले selectAds() रन की एकल सूची.
  • विज्ञापन चुनने के सिग्नल: यह एक JSON ऑब्जेक्ट है, जिसे स्ट्रिंग के तौर पर सीरियलाइज़ किया गया है. इसमें बिडिंग के लिए खरीदार के लॉजिक का इस्तेमाल करने वाले सिग्नल होते हैं. इस मामले में, दिए गए तीसरे पक्ष के नेटवर्क के लिए, बिड फ़्लोर को शामिल करें.
  • विज्ञापन चुनने का लॉजिक यूआरआई: विज्ञापन चुनने के दौरान क्वेरी किया गया एचटीटीपीएस यूआरएल, ताकि विज्ञापन चुनने के लिए मीडिएशन नेटवर्क का 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 बनाएं. इसमें 1P outcomeId और तीसरे पक्ष के एसडीके टूल की बिड फ़्लोर शामिल करें.
    2. पिछले चरण में दिए गए कॉन्फ़िगरेशन के साथ selectAds() को कॉल करें.
    3. अगर नतीजा खाली नहीं है, तो विज्ञापन दिखाएं.
    4. मौजूदा SDK टूल के नेटवर्क अडैप्टर के selectAds() तरीके को कॉल करें. अगर नतीजा खाली नहीं है, तो विज्ञापन दिखाएं.
  3. अगर चेन में कोई विज्ञापन नहीं मिलता है, तो 1P विज्ञापन दिखाएं.

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

विज्ञापन इंप्रेशन की शिकायत करना

नीलामी के तरीके के आधार पर, विज्ञापन इंप्रेशन की रिपोर्टिंग के लिए दो फ़्लो होते हैं. अगर आप एक ऐसे एसएसपी हैं जो नीलामी चला रहा है, तो इस सेक्शन में दिया गया तरीका अपनाएं. अगर आपको वॉटरफ़ॉल मीडिएशन लागू करना है, तो वॉटरफ़ॉल मीडिएशन इंप्रेशन रिपोर्टिंग सेक्शन में दिया गया तरीका अपनाएं.

किसी एक एसएसपी के इंप्रेशन की रिपोर्टिंग

विज्ञापन चुनने के वर्कफ़्लो से विज्ञापन चुनने के बाद, AdSelectionManager.reportImpression() तरीके का इस्तेमाल करके, इंप्रेशन को फिर से उन बाय-साइड और सेल-साइड प्लैटफ़ॉर्म को रिपोर्ट किया जा सकता है जो इस प्रोग्राम में हिस्सा ले रहे हैं. विज्ञापन इंप्रेशन की शिकायत करने के लिए:

  1. AdSelectionManager ऑब्जेक्ट को शुरू करना.
  2. विज्ञापन चुनने के आईडी की मदद से, ReportImpressionRequest ऑब्जेक्ट बनाएं.
  3. ReportImpressionRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एक साथ काम करने वाले reportImpression() तरीके को कॉल करें.

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() कॉलबैक से पता चलता है कि इंप्रेशन रिपोर्टिंग यूआरएल बनाए गए हैं या नहीं और अनुरोध शेड्यूल किया गया है या नहीं.
  • onError() कॉलबैक, इन संभावित स्थितियों के बारे में बताता है:
    • अगर कॉल को अमान्य इनपुट आर्ग्युमेंट से शुरू किया जाता है, तो AdServicesException, IllegalArgumentException को वजह के तौर पर दिखाता है.
    • अन्य सभी गड़बड़ियों के लिए, AdServicesException को गड़बड़ी की वजह के तौर पर IllegalStateException के साथ दिखाया जाता है.

वॉटरफ़ॉल मीडिएशन इंप्रेशन रिपोर्टिंग

रिपोर्टिंग फ़्लो को ट्रिगर करने के लिए, मीडिएशन SDK टूल को विजेता SDK टूल पर नज़र रखनी होगी. मीडिएशन चेन में हिस्सा लेने वाले SDK, मीडिएटर को अपना रिपोर्टिंग फ़्लो ट्रिगर करने के लिए, कोई तरीका उपलब्ध कराने चाहिए. मीडिएशन वाली नीलामी में हिस्सा लेने वाला SDK टूल, अपनी रिपोर्टिंग लागू करने के लिए ऊपर दिए गए तरीके का इस्तेमाल कर सकता है.

एसएसपी, मीडिएशन फ़्लो में शामिल होने के तरीके के प्रोटोटाइप के तौर पर, तीसरे पक्ष के एसडीके कोड के इस उदाहरण का इस्तेमाल कर सकते हैं:

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

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

इंप्रेशन रिपोर्टिंग एंडपॉइंट

रिपोर्ट इंप्रेशन एपीआई, सेल-साइड प्लैटफ़ॉर्म और विजेता बाय-साइड प्लैटफ़ॉर्म से मिले एंडपॉइंट पर एचटीटीपीएस GET अनुरोध भेजता है:

बाय-साइड प्लैटफ़ॉर्म का एंडपॉइंट:

  • एपीआई, कस्टम ऑडियंस में बताए गए बिडिंग लॉजिक यूआरएल का इस्तेमाल करके, खरीदार से मिले JavaScript को फ़ेच करता है. इसमें इंप्रेशन रिपोर्टिंग यूआरएल दिखाने के लिए लॉजिक शामिल होता है.
  • reportWin() JavaScript फ़ंक्शन को चालू करें. इससे खरीदार के इंप्रेशन की रिपोर्टिंग का यूआरएल दिखेगा.

सेल-साइड प्लैटफ़ॉर्म का एंडपॉइंट:

  • सेलर के फ़ैसले के लॉजिक JavaScript को फ़ेच करने के लिए, AdSelectionConfig ऑब्जेक्ट में दिए गए फ़ैसले के लॉजिक यूआरएल का इस्तेमाल करें.
  • reportResult() JavaScript फ़ंक्शन को लागू करें. इससे सेलर के इंप्रेशन की रिपोर्टिंग का यूआरएल दिखेगा.

बिडिंग और नीलामी से जुड़ी सेवाओं की रिपोर्टिंग

बिडिंग और नीलामी की सेवाओं पर की गई नीलामी में, रिपोर्टिंग से जुड़ी सभी ज़रूरी जानकारी होगी. इसमें, सर्वर-साइड नीलामी से मिले एन्क्रिप्ट किए गए जवाब में, विज्ञापन इंटरैक्शन रिपोर्टिंग के लिए जनरेट किए गए यूआरएल भी शामिल होंगे. रिस्पॉन्स को डिक्रिप्ट करने के बाद, प्लैटफ़ॉर्म पर सही यूआरएल रजिस्टर किए जाते हैं, ताकि विज्ञापन और इंप्रेशन रिपोर्टिंग एक ही तरीके से हो.

इंप्रेशन की रिपोर्टिंग के लिए, पूरी कोशिश करना

reportImpression() तरीके को रिपोर्टिंग को बेहतर तरीके से पूरा करने के लिए डिज़ाइन किया गया है.

विज्ञापन से इंटरैक्शन की शिकायत करना

Protected Audience, रेंडर किए गए विज्ञापन के लिए ज़्यादा जानकारी वाले इंटरैक्शन की रिपोर्ट करने में मदद करता है. इसमें इंटरैक्शन शामिल हो सकते हैं, जैसे कि वीडियो देखने का कुल समय, क्लिक, कर्सर घुमाना या इकट्ठा की जा सकने वाली कोई भी दूसरी काम की मेट्रिक. ये रिपोर्ट पाने के लिए, दो चरण पूरे करने होंगे. सबसे पहले, खरीदारों और सेलर को अपने रिपोर्टिंग JavaScript में ये रिपोर्ट पाने के लिए रजिस्टर करना होगा. इसके बाद, क्लाइंट को इन इवेंट की रिपोर्ट देनी होगी.

इंटरैक्शन इवेंट पाने के लिए रजिस्टर करना

इंटरैक्शन इवेंट के लिए रजिस्टर करने की प्रोसेस, खरीदार के reportWin() और सेलर के reportResult() JavaScript फ़ंक्शन में होती है. इसके लिए, प्लैटफ़ॉर्म से मिले 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. request ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एसिंक्रोनस reportInteraction() तरीके को कॉल करें.
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 दिखाया जाता है.
    • अगर पैकेज को निजता बनाए रखने वाले एपीआई को कॉल करने के लिए रजिस्टर नहीं किया गया है, तो SecurityException() दिखाया जाता है.
    • अगर इंटरैक्शन की रिपोर्टिंग करने वाला ऐप्लिकेशन, selectAds() को कॉल करने वाले ऐप्लिकेशन से अलग है, तो IllegalStateException दिखाया जाता है.
  • अगर उपयोगकर्ता ने Privacy Sandbox API को चालू करने की सहमति नहीं दी है, तो कॉल चुपचाप बंद हो जाएगा.

इंटरैक्शन रिपोर्टिंग एंडपॉइंट

रिपोर्ट इंटरैक्शन एपीआई, सेल-साइड प्लैटफ़ॉर्म और विजेता बाय-साइड प्लैटफ़ॉर्म से मिले एंडपॉइंट पर एचटीटीपीएस पोस्ट अनुरोध भेजता है. सुरक्षित ऑडियंस, इंटरैक्शन की कुंजियों को रिपोर्टिंग JavaScript में बताए गए यूआरआई से मैच करेगी. साथ ही, रिपोर्ट किए जा रहे हर इंटरैक्शन के लिए, हर एंडपॉइंट पर एक पोस्ट अनुरोध जारी करेगी. अनुरोध का Content-Type, सादा टेक्स्ट होता है. इसमें मुख्य हिस्सा, इंटरैक्शन डेटा होता है.

इंटरैक्शन की रिपोर्टिंग के लिए, पूरी कोशिश करना

reportInteraction() को एचटीटीपी पोस्ट के ज़रिए रिपोर्टिंग को बेहतर तरीके से पूरा करने के लिए डिज़ाइन किया गया है.

बैकग्राउंड में हर दिन होने वाला अपडेट

कस्टम ऑडियंस बनाते समय, आपका ऐप्लिकेशन या SDK टूल, कस्टम ऑडियंस के मेटाडेटा को शुरू कर सकता है. इसके अलावा, प्लैटफ़ॉर्म हर दिन बैकग्राउंड में अपडेट होने की प्रोसेस की मदद से, कस्टम ऑडियंस के मेटाडेटा के इन हिस्सों को अपडेट कर सकता है.

  • उपयोगकर्ता के बिडिंग सिग्नल
  • भरोसेमंद बिडिंग डेटा
  • AdData सूची

यह प्रोसेस, कस्टम ऑडियंस में तय किए गए, रोज़ अपडेट होने वाले यूआरएल के लिए क्वेरी करती है. साथ ही, यह यूआरएल JSON रिस्पॉन्स दिखा सकता है.

  • JSON रिस्पॉन्स में, काम करने वाले किसी भी मेटाडेटा फ़ील्ड की वैल्यू शामिल हो सकती है.
  • हर JSON फ़ील्ड की पुष्टि अलग से की जाती है. क्लाइंट, गलत तरीके से बनाए गए किसी भी फ़ील्ड को अनदेखा करता है. इस वजह से, जवाब में उस फ़ील्ड में कोई अपडेट नहीं होता.
  • खाली एचटीटीपी रिस्पॉन्स या खाली JSON ऑब्जेक्ट "{}" से, मेटाडेटा अपडेट नहीं होता.
  • रिस्पॉन्स मैसेज का साइज़ 10 केबी से ज़्यादा नहीं होना चाहिए.
  • सभी यूआरआई के लिए एचटीटीपीएस का इस्तेमाल करना ज़रूरी है.
  • trusted_bidding_uri का ईटीएलडी+1, खरीदार के ईटीएलडी+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 को कस्टम ऑडियंस में बताए गए बिडिंग लॉजिक यूआरएल से फ़ेच किया जाता है. रिटर्न किए गए JavaScript में ये फ़ंक्शन शामिल होने चाहिए:

विज्ञापन चुनने वाले एपीआई के लिए AdSelectionConfig पैरामीटर में बताए गए फ़ैसले के लॉजिक यूआरएल से, सेलर का दिया गया JavaScript फ़ेच किया जाता है. रिटर्न किए गए JavaScript में ये फ़ंक्शन शामिल होने चाहिए:

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: var ad = { 'render_url': url, 'metadata': json_metadata }; फ़ॉर्मैट वाला JSON ऑब्जेक्ट
  • auction_signals, per_buyer_signals: नीलामी कॉन्फ़िगरेशन ऑब्जेक्ट में बताए गए JSON ऑब्जेक्ट
  • custom_audience_bidding_signals: प्लैटफ़ॉर्म से जनरेट किया गया JSON ऑब्जेक्ट. इस JSON ऑब्जेक्ट का फ़ॉर्मैट यह है:

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

    कहां:

    • owner, buyer, और name, विज्ञापन चुनने में हिस्सा लेने वाली कस्टम ऑडियंस के एक जैसे नाम वाली प्रॉपर्टी से ली गई स्ट्रिंग हैं
    • activation_time और expiration_time, कस्टम ऑडियंस के चालू होने और खत्म होने का समय है. इसे Unix युग के बाद के सेकंड में दिखाया जाता है
    • ca_user_bidding_signals, CustomAudience बनाते समय, userBiddingSignals फ़ील्ड में बताई गई JSON स्ट्रिंग है
    • 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: selectAds एपीआई के AdSelectionConfig पैरामीटर को दिखाने वाला JSON ऑब्जेक्ट. फ़ॉर्मैट यह है:

    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: sellerSignals AdSelectionConfig API पैरामीटर से पढ़े गए JSON ऑब्जेक्ट

  • trusted_scoring_signal: AdSelectionConfig एपीआई पैरामीटर में adSelectionSignals फ़ील्ड से पढ़ें

  • contextual_signals, user_signals: JSON ऑब्जेक्ट. इन्हें खाली ऑब्जेक्ट के तौर पर पास किया जाता है और आने वाले समय में रिलीज़ होने वाले वर्शन में इन्हें भर दिया जाएगा. इनका फ़ॉर्मैट, प्लैटफ़ॉर्म से लागू नहीं किया जाता. साथ ही, इन्हें विज्ञापन टेक्नोलॉजी से मैनेज किया जाता है.

  • per_buyer_signals: AdSelectionConfig एपीआई पैरामीटर में perBuyerSignal मैप से पढ़ा गया JSON ऑब्जेक्ट. इसमें मौजूदा कस्टम ऑडियंस के खरीदार को पासकोड के तौर पर इस्तेमाल किया जाता है. अगर मैप में खरीदार की जानकारी मौजूद नहीं है, तो यह फ़ील्ड खाली रहेगा.

आउटपुट:

  • 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, सफल होने पर 0 से ज़्यादा और न होने पर 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: विज्ञापन के रेंडर किए गए यूआरएल का पता
  • bid: विज्ञापन दिखाने के लिए सबमिट की गई बिड
  • contextual_signals: generateBid का दस्तावेज़ देखें

आउटपुट:

  • सफल होने पर status: 0 और न होने पर शून्य से ज़्यादा
  • results: JSON ऑब्जेक्ट, जिसमें ये शामिल हैं:
    • signals_for_buyer: reportWin फ़ंक्शन में पास किया गया JSON ऑब्जेक्ट
    • reporting_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: reportResult से मिला JSON ऑब्जेक्ट
  • contextual_signals, custom_audience_signals: generateBid के लिए दस्तावेज़ देखें

आउटपुट:

  • status: 0 के लिए सफल और गैर-शून्य के लिए गड़बड़ी
  • results: एक JSON ऑब्जेक्ट, जिसमें ये शामिल हैं:
    • reporting_url: ऐसा यूआरएल जिसका इस्तेमाल प्लैटफ़ॉर्म, सेलर को इंप्रेशन की सूचना देने के लिए करता है

registerAdBeacon()

function registerAdBeacon(
  beacons
)

इनपुट पैरामीटर:

  • beacons: यह ऐसा ऑब्जेक्ट है जिसमें इंटरैक्शन कुंजियों और रिपोर्टिंग यूआरआई के की-वैल्यू पेयर होते हैं. इसका फ़ॉर्मैट यह है:

    let beacons = {
      'interaction_key': 'reporting_uri',
      'interaction_key': 'reporting_uri',
      ...
    }
    
    • interaction_key: इवेंट की जानकारी देने वाली स्ट्रिंग. इवेंट इंटरैक्शन की रिपोर्टिंग करते समय, प्लैटफ़ॉर्म इसका इस्तेमाल बाद में करता है. इससे, उस reporting_uri को ढूंढा जाता है जिसे सूचना देनी है. यह कुंजी, खरीदार या सेलर के रजिस्टर किए गए प्रॉडक्ट और सेलर की रिपोर्ट में मौजूद प्रॉडक्ट से मेल खानी चाहिए.
    • reporting_uri: इवेंट रिपोर्ट पाने के लिए यूआरआई. यह, रिपोर्ट किए जा रहे इवेंट टाइप के हिसाब से होना चाहिए. इवेंट के साथ रिपोर्ट किए गए किसी भी डेटा को मैनेज करने के लिए, इसे POST अनुरोध स्वीकार करना होगा.

    उदाहरण के लिए:

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

विज्ञापन चुनने के लिए पहले से बने यूआरआई

पहले से बने यूआरआई की मदद से, विज्ञापन टेक्नोलॉजी कंपनियां AdSelectionConfig और AdSelectionFromOutcomesConfig क्लास में, विज्ञापन चुनने के फ़ैसले के लॉजिक के लिए JavaScript फ़ंक्शन तय कर सकती हैं. पहले से बने यूआरआई के लिए, उनसे जुड़े JavaScript को डाउनलोड करने के लिए नेटवर्क कॉल की ज़रूरत नहीं होती. विज्ञापन टेक्नोलॉजी विशेषज्ञ, पहले से बने यूआरएल का इस्तेमाल कर सकते हैं. इसके लिए, उन्हें JavaScript को होस्ट करने के लिए, रजिस्टर किया गया डोमेन सेट अप करने की ज़रूरत नहीं होती.

पहले से तैयार यूआरआई को इस फ़ॉर्मैट का इस्तेमाल करके बनाया जाता है:

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

Privacy Sandbox प्लैटफ़ॉर्म, रनटाइम में इस यूआरआई की जानकारी का इस्तेमाल करके JavaScript उपलब्ध कराता है.

IllegalArgumentException तब दिखता है, जब:

  • यूआरआई में कोई भी ज़रूरी पैरामीटर मौजूद नहीं है
  • यूआरआई में ऐसे पैरामीटर हैं जिन्हें पहचाना नहीं जा सका

पहले से बने यूआरआई के इस्तेमाल के उदाहरण और नाम

इस्तेमाल का पहला उदाहरण: विज्ञापन चुनना

ad-selection इस्तेमाल के उदाहरण के तहत, पहले से बने यूआरआई, selectAds(AdSelectionConfig) फ़्लो में काम करते हैं.

पहले से बने यूआरआई का नाम: highest-bid-wins

पहले से तैयार किया गया यह यूआरआई, एक JavaScript उपलब्ध कराता है. यह JavaScript, बिडिंग के बाद सबसे ज़्यादा बिड वाला विज्ञापन चुनता है. इसमें, विजेता के render_uri और bid की जानकारी देने के लिए, रिपोर्टिंग का एक बुनियादी फ़ंक्शन भी दिया गया है.

ज़रूरी पैरामीटर

reportingUrl: रिपोर्टिंग का बुनियादी यूआरएल, जो विजेता विज्ञापन के render_uri और bid के साथ पैरामीटर किया गया है:

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

इस्तेमाल किए जाने से जुड़ी जानकारी

अगर आपका बेस रिपोर्टिंग यूआरएल https://www.ssp.com/reporting है, तो पहले से बना यूआरआई यह होगा:

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

इस्तेमाल का दूसरा उदाहरण: नतीजों के आधार पर विज्ञापन चुनना

ad-selection-from-outcomes इस्तेमाल के उदाहरण में पहले से बने यूआरआई, selectAds(AdSelectionFromOutcomesConfig) वर्कफ़्लो के साथ काम करते हैं.

पहले से बने यूआरआई का नाम: waterfall-mediation-truncation

waterfall-mediation-truncation पहले से बना यूआरआई, JavaScript उपलब्ध कराता है. यह वॉटरफ़ॉल मीडिएशन ट्रिंकेटेशन लॉजिक लागू करता है. इसमें JavaScript, bid के bid floor से ज़्यादा या उसके बराबर होने पर, पहला पक्ष का विज्ञापन दिखाता है. इसके अलावा, bid के bid floor से कम होने पर, null दिखाता है.

ज़रूरी पैरामीटर

bidFloor: getSelectionSignals() में पास की गई बिड फ़्लोर वैल्यू की वह कुंजी जिसकी तुलना मीडिएशन SDK टूल के विज्ञापन से की जाती है.

इस्तेमाल किए जाने से जुड़ी जानकारी

अगर आपके विज्ञापन चुनने के सिग्नल {"bid_floor": 10} जैसे दिखते हैं, तो पहले से तैयार यूआरआई इस तरह दिखेगा:

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

टेस्ट करना

Protected Audience API का इस्तेमाल शुरू करने में आपकी मदद करने के लिए, हमने Kotlin और Java में सैंपल ऐप्लिकेशन बनाए हैं. इन्हें GitHub पर देखा जा सकता है.

ज़रूरी शर्तें

विज्ञापन चुनने और इंप्रेशन रिपोर्टिंग के दौरान, Protected Audience API को कुछ JavaScript की ज़रूरत होती है. इस JavaScript को टेस्टिंग एनवायरमेंट में उपलब्ध कराने के दो तरीके हैं:

  • ज़रूरी एचटीटीपीएस एंडपॉइंट वाला सर्वर चलाएं, जो JavaScript दिखाता हो
  • किसी स्थानीय सोर्स से ज़रूरी कोड देकर, रिमोट फ़ेचिंग को बदलना

इनमें से किसी भी तरीके को अपनाने के लिए, इंप्रेशन की रिपोर्टिंग को मैनेज करने के लिए एचटीटीपीएस एंडपॉइंट सेट अप करना ज़रूरी है.

एचटीटीपीएस एंडपॉइंट

विज्ञापन चुनने और इंप्रेशन रिपोर्टिंग की जांच करने के लिए, आपको सात एचटीटीपीएस एंडपॉइंट सेट अप करने होंगे. ये एंडपॉइंट, आपके टेस्ट डिवाइस या एमुलेटर ऐक्सेस कर सकते हैं:

  1. बिडिंग लॉजिक JavaScript को दिखाने वाला खरीदार एंडपॉइंट.
  2. बिडिंग सिग्नल दिखाने वाला एंडपॉइंट.
  3. सेलर का वह एंडपॉइंट जो फ़ैसले का लॉजिक JavaScript दिखाता है.
  4. स्कोरिंग सिग्नल देने वाला एंडपॉइंट.
  5. खरीदार के इंप्रेशन की रिपोर्टिंग का एंडपॉइंट.
  6. सेलर इंप्रेशन रिपोर्टिंग एंडपॉइंट.
  7. कस्टम ऑडियंस के लिए, रोज़ के अपडेट दिखाने वाला एंडपॉइंट.

GitHub रिपॉज़िटरी में, जांच के लिए बुनियादी JavaScript कोड उपलब्ध होता है, ताकि आपको आसानी से काम करने में मदद मिल सके. इसमें OpenAPI सेवा की परिभाषाएं भी शामिल हैं, जिन्हें काम करने वाले मॉक या माइक्रोसर्विस प्लैटफ़ॉर्म पर डिप्लॉय किया जा सकता है. ज़्यादा जानकारी के लिए, प्रोजेक्ट का README देखें.

JavaScript को रिमोट से फ़ेच करने की सुविधा को बदलना

इस सुविधा का इस्तेमाल, एंड-टू-एंड टेस्टिंग के लिए किया जाता है. रिमोट फ़ेचिंग को बदलने के लिए, आपका ऐप्लिकेशन डीबग मोड में चलना चाहिए. साथ ही, डेवलपर के लिए सेटिंग और टूल चालू होने चाहिए.

अपने ऐप्लिकेशन के लिए डीबग मोड चालू करने के लिए, अपने AndroidManifest.xml में ऐप्लिकेशन एट्रिब्यूट में यह लाइन जोड़ें:

<application
  android:debuggable="true">

इन बदलावों का इस्तेमाल करने का उदाहरण देखने के लिए, GitHub पर Protected Audience API का सैंपल ऐप्लिकेशन देखें.

विज्ञापन चुनने के रूटीन को मैनेज करने के लिए, आपको अपना कस्टम JavaScript जोड़ना होगा. जैसे, बिडिंग, स्कोरिंग के फ़ैसले, और रिपोर्टिंग. GitHub रिपॉज़िटरी में, JavaScript के बेसिक कोड के ऐसे उदाहरण मिल सकते हैं जो सभी ज़रूरी अनुरोधों को मैनेज करते हैं. Protected Audience API के सैंपल ऐप्लिकेशन में, उस फ़ाइल से कोड पढ़ने और उसे बदलाव करने के लिए तैयार करने का तरीका बताया गया है.

सेल-साइड और बाय-साइड JavaScript फ़ेचिंग को अलग-अलग तरीके से बदला जा सकता है. हालांकि, आपको किसी भी ऐसे JavaScript को दिखाने के लिए एचटीटीपीएस एंडपॉइंट की ज़रूरत होगी जिसके लिए आपने बदलाव नहीं किए हैं. इन मामलों को मैनेज करने वाला सर्वर सेट अप करने का तरीका जानने के लिए, README देखें.

JavaScript फ़ेचिंग को सिर्फ़ उन कस्टम ऑडियंस के लिए बदला जा सकता है जिनका मालिकाना हक आपके पास है.

सेल-साइड JavaScript को बदलना

सेल-साइड JavaScript को बदलने के लिए, नीचे दिए गए कोड उदाहरण में दिखाए गए तरीके से ऐसा करें:

  1. AdSelectionManager ऑब्जेक्ट को शुरू करना.
  2. AdSelectionManager ऑब्जेक्ट से TestAdSelectionManager का रेफ़रंस पाएं.
  3. AdSelectionConfig ऑब्जेक्ट बनाएं.
  4. AdSelectionConfig ऑब्जेक्ट और String के साथ AddAdSelectionOverrideRequest बनाएं. String से उस JavaScript को दिखाया जाता है जिसे आपको बदलाव करने के लिए इस्तेमाल करना है.
  5. AddAdSelectionOverrideRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एक साथ काम करने वाले overrideAdSelectionConfigRemoteInfo() तरीके को कॉल करें.

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 फ़ाइल को स्ट्रिंग के तौर पर पढ़ने का उदाहरण देखने के लिए, GitHub पर Protected Audience API का सैंपल ऐप्लिकेशन देखें.

एपीआई कॉल के नतीजे का सिग्नल देने के लिए, असाइनोक्रोनस 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);

सेल-साइड ओवरराइड रीसेट करने के बाद, ज़रूरी JavaScript फ़ेच करने के लिए, selectAds() के कॉल में AdSelectionConfig में सेव किए गए decisionLogicUrl का इस्तेमाल किया जाता है.

अगर resetAllAdSelectionConfigRemoteOverrides() को कॉल करने में कोई समस्या आती है, तो OutComeReceiver.onError() कॉलबैक AdServiceException दिखाता है. अगर डेवलपर के विकल्प चालू होने के साथ, डीबग मोड में काम न करने वाले ऐप्लिकेशन से बदलावों को हटाने की कोशिश की जाती है, तो AdServiceException, IllegalStateException को वजह के तौर पर दिखाता है.

बाय-साइड JavaScript को बदलना

  1. कस्टम ऑडियंस से जुड़ने के लिए यह तरीका अपनाएं
  2. आपको जिस कस्टम ऑडियंस को बदलना है उसके खरीदार और नाम के साथ AddCustomAudienceOverrideRequest बनाएं. साथ ही, बिडिंग लॉजिक और उस डेटा को भी बनाएं जिसका इस्तेमाल आपको बदलाव करने के लिए करना है.
  3. AddCustomAudienceOverrideRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एसिंक्रोनस overrideCustomAudienceRemoteInfo() तरीके को कॉल करें.

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 को वजह के तौर पर दिखाता है.

बाय-साइड ओवरराइड रीसेट करना

इस सेक्शन में यह माना गया है कि आपने buy-side JavaScript को बदल दिया है और आपके पास पिछले सेक्शन में इस्तेमाल किए गए TestCustomAudienceManager का रेफ़रंस है.

सभी कस्टम ऑडियंस के लिए बदलावों को रीसेट करने के लिए:

  1. काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एसिंक्रोनस resetAllCustomAudienceOverrides() मेथड को कॉल करें.

Kotlin

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

Java

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

खरीदार की ओर से किए गए बदलावों को रीसेट करने के बाद, ज़रूरी JavaScript फ़ेच करने के लिए, selectAds() पर किए जाने वाले बाद के कॉल में, CustomAudience में सेव किए गए biddingLogicUrl और trustedBiddingData का इस्तेमाल किया जाता है.

अगर resetCustomAudienceRemoteInfoOverride() को कॉल करने में कोई समस्या आती है, तो OutComeReceiver.onError() कॉलबैक AdServiceException दिखाता है. अगर डेवलपर के विकल्प चालू होने के साथ, डीबग मोड में काम न करने वाले ऐप्लिकेशन से बदलावों को हटाने की कोशिश की जाती है, तो AdServiceException, IllegalStateException को वजह के तौर पर दिखाता है.

रिपोर्टिंग सर्वर सेट अप करना

रिमोट फ़ेचिंग बदलावों का इस्तेमाल करने पर भी, आपको एक ऐसा सर्वर सेट अप करना होगा जिस पर आपका डिवाइस या एमुलेटर, रिपोर्टिंग इवेंट का जवाब दे सके. जांच करने के लिए, ऐसा एंडपॉइंट चुनें जो 200 कोड दिखाता हो. GitHub रिपॉज़िटरी में, OpenAPI सेवा की परिभाषाएं शामिल होती हैं. इन्हें, काम करने वाले मॉक या माइक्रोसर्विस प्लैटफ़ॉर्म पर डिप्लॉय किया जा सकता है. ज़्यादा जानकारी के लिए, प्रोजेक्ट का README देखें.

OpenAPI डेफ़िनिशन खोजते समय, reporting-server.json देखें. इस फ़ाइल में एक एंडपॉइंट है, जो 200 दिखाता है. यह एचटीटीपी रिस्पॉन्स कोड दिखाता है. इस एंडपॉइंट का इस्तेमाल selectAds() के दौरान किया जाता है. साथ ही, इससे Protected Audience API को यह सिग्नल मिलता है कि इंप्रेशन रिपोर्टिंग पूरी हो गई है.

जांचने के लिए फ़ंक्शन

  • उपयोगकर्ता की पिछली कार्रवाइयों के आधार पर, कस्टम ऑडियंस सेट अप करना और उसमें शामिल होना या उससे बाहर निकलना.
  • डिवाइस पर विज्ञापन चुनने की प्रोसेस को शुरू करने के लिए, रिमोट तौर पर होस्ट किए गए JavaScript का इस्तेमाल करें.
  • देखें कि कस्टम ऑडियंस सेटिंग के साथ किसी ऐप्लिकेशन के जुड़ाव से, विज्ञापन चुनने के नतीजों पर क्या असर पड़ सकता है.
  • विज्ञापन चुनने के बाद, इंप्रेशन रिपोर्टिंग का इस्तेमाल करें.

सीमाएं

यहां दी गई टेबल में, Protected Audience API की प्रोसेसिंग से जुड़ी सीमाओं के बारे में बताया गया है. सुझाव/राय/शिकायत के आधार पर, सीमाओं में बदलाव किया जा सकता है. जिन सुविधाओं पर काम चल रहा है उनके बारे में जानने के लिए, रिलीज़ नोट पढ़ें.

कॉम्पोनेंट सीमा की जानकारी सीमा की वैल्यू
कस्टम ऑडियंस (सीए) हर सीए में विज्ञापनों की ज़्यादा से ज़्यादा संख्या 100
हर ऐप्लिकेशन के लिए सीए की ज़्यादा से ज़्यादा संख्या 1000
ज़्यादा से ज़्यादा कितने ऐप्लिकेशन सीए बना सकते हैं 1000
सीए बनाने के बाद, उसे चालू होने में लगने वाला ज़्यादा से ज़्यादा समय 60 दिन
सीए के चालू होने के समय से, उसकी समयसीमा खत्म होने का ज़्यादा से ज़्यादा समय 60 दिन
डिवाइस पर ज़्यादा से ज़्यादा सीए की संख्या 4000
सीए के नाम का ज़्यादा से ज़्यादा साइज़ 200 बाइट
हर दिन फ़ेच किए जाने वाले यूआरआई का ज़्यादा से ज़्यादा साइज़ 400 बाइट
बिडिंग लॉजिक यूआरआई का ज़्यादा से ज़्यादा साइज़ 400 बाइट
भरोसेमंद बिडिंग डेटा का ज़्यादा से ज़्यादा साइज़ 10 केबी
उपयोगकर्ता बिडिंग सिग्नल का ज़्यादा से ज़्यादा साइज़ 10 केबी
हर खरीदार के लिए leaveCustomAudience का ज़्यादा से ज़्यादा कॉल रेट हर सेकंड में 1
हर खरीदार के लिए joinCustomAudience का ज़्यादा से ज़्यादा कॉल रेट हर सेकंड में 1
कनाडा में बैकग्राउंड फ़ेच की सुविधा कनेक्‍शन समयबाह्य 5 सेकंड
एचटीटीपी पढ़ने का टाइम आउट 30 सेकंड
डाउनलोड किए जाने वाले वीडियो का ज़्यादा से ज़्यादा साइज़ 10 केबी
फ़ेच करने के लिए, एक बार में ज़्यादा से ज़्यादा कितनी बार डेटा लिया जा सकता है 5 मिनट
हर जॉब के लिए अपडेट किए गए सीए की ज़्यादा से ज़्यादा संख्या 1000
विज्ञापन चुनना खरीदारों की ज़्यादा से ज़्यादा संख्या अभी तय नहीं है
हर खरीदार के लिए सीए की ज़्यादा से ज़्यादा संख्या अभी तय नहीं है
नीलामी में विज्ञापनों की ज़्यादा से ज़्यादा संख्या अभी तय नहीं है
शुरुआती कनेक्शन टाइम आउट 5 सेकंड
कनेक्शन पढ़ने का समय खत्म हो गया 5 सेकंड
कुल AdSelection का ज़्यादा से ज़्यादा निष्पादन समय 10 सेकंड
AdSelection में हर सीए के लिए, बिडिंग के ज़्यादा से ज़्यादा समय का निष्पादन पांच सेकंड
AdSelection में स्कोरिंग का ज़्यादा से ज़्यादा समय पांच सेकंड
AdSelection में हर खरीदार के लिए, ज़्यादा से ज़्यादा निष्पादन समय अभी तय नहीं है
विज्ञापन चुनने/सेलर/हर खरीदार के सिग्नल का ज़्यादा से ज़्यादा साइज़ अभी तय नहीं है
सेलर/बाइअर स्क्रिप्ट का ज़्यादा से ज़्यादा साइज़ अभी तय नहीं है
selectAds के लिए कॉल रेट की ज़्यादा से ज़्यादा सीमा 1 क्यूपीएस
इंप्रेशन रिपोर्टिंग विज्ञापन चुनने की सेटिंग को 'इस्तेमाल में है' सेक्शन से हटाने से पहले, कम से कम कितने समय तक उसे सेव रखना चाहिए 24 घंटे
स्टोरेज विज्ञापनों की ज़्यादा से ज़्यादा संख्या अभी तय नहीं है
रिपोर्टिंग आउटपुट यूआरएल का ज़्यादा से ज़्यादा साइज़ अभी तय नहीं है
इंप्रेशन रिपोर्टिंग के लिए ज़्यादा से ज़्यादा समय अभी तय नहीं है
सूचना वाले कॉल के लिए, फिर से कोशिश करने की ज़्यादा से ज़्यादा संख्या अभी तय नहीं है
कनेक्शन टाइम आउट 5 सेकंड
reportImpression के लिए, एक बार में ज़्यादा से ज़्यादा कितनी बार चलाया जा सकता है 2 सेकंड
reportImpressions के लिए कॉल रेट की ज़्यादा से ज़्यादा सीमा 1 क्यूपीएस
इवेंट की जानकारी रिपोर्ट करने की सुविधा हर ऑक्शन में हर खरीदार के लिए ज़्यादा से ज़्यादा बीकन की संख्या 10

हर सेलर के लिए, हर नीलामी में ज़्यादा से ज़्यादा बीकन की संख्या

10

इवेंट बटन का ज़्यादा से ज़्यादा साइज़

40 बाइट

इवेंट डेटा का ज़्यादा से ज़्यादा साइज़

64 केबी

विज्ञापन विज्ञापन सूची का ज़्यादा से ज़्यादा साइज़ कॉन्टेक्स्ट के हिसाब से जानकारी दिखाने के लिए, एक ही सीए में सभी AdData ने 10 केबी का डेटा शेयर किया
यूआरएल इनपुट के तौर पर ली गई किसी भी यूआरएल स्ट्रिंग की ज़्यादा से ज़्यादा लंबाई अभी तय नहीं है
Javascript प्रोसेस पूरी होने में लगने वाला ज़्यादा से ज़्यादा समय इंप्रेशन रिपोर्टिंग के लिए बिडिंग और स्कोरिंग में एक सेकंड
ज़्यादा से ज़्यादा मेमोरी का इस्तेमाल 10 MB

गड़बड़ियों और समस्याओं की शिकायत करना

Android पर Privacy Sandbox को बेहतर बनाने के लिए, आपका सुझाव, राय या शिकायत हमारे लिए अहम है! अगर आपको कोई समस्या आती है या Android पर Privacy Sandbox को बेहतर बनाने के लिए कोई सुझाव है, तो हमें बताएं.