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

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

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

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

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

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

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

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

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

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

1. Android पर Privacy Sandbox के लिए, अपना डेवलपमेंट एनवायरमेंट सेट अप करें.
2. Privacy Sandbox on Android के साथ काम करने वाले डिवाइस पर सिस्टम इमेज इंस्टॉल करें या 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. विज्ञापन सेवाओं से जुड़ी अनुमतियों और एसडीके के ऐक्सेस कंट्रोल के बारे में ज़्यादा जानें.

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

8. डिफ़ॉल्ट रूप से, Ad Selection API, नीलामी या इंप्रेशन रिपोर्टिंग स्क्रिप्ट के लिए, ज़्यादा से ज़्यादा मेमोरी की सीमाएं लागू करता है. मेमोरी की सीमा तय करने की सुविधा के लिए, WebView 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() को कॉल करें.

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

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

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

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

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

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

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

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

किसी डिवाइस पर मौजूद हर CustomAudience ऑब्जेक्ट की पहचान, यहां दिए गए पैरामीटर के कॉम्बिनेशन से की जाती है:

• owner: मालिक ऐप्लिकेशन के पैकेज का नाम. यह कॉलर ऐप्लिकेशन के पैकेज के नाम पर अपने-आप सेट हो जाता है.
• buyer: यह खरीदार के विज्ञापन नेटवर्क का आइडेंटिफ़ायर है. यह नेटवर्क, इस कस्टम ऑडियंस के लिए विज्ञापन मैनेज करता है.
• name: कस्टम ऑडियंस के लिए कोई भी नाम या आइडेंटिफ़ायर.

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

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

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

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

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

यहां CustomAudience ऑब्जेक्ट इंस्टैंटिएशन का उदाहरण दिया गया है:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

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

एसिंक्रोनस joinCustomAudience() तरीका, एपीआई कॉल के नतीजे के बारे में बताने के लिए OutcomeReceiver ऑब्जेक्ट का इस्तेमाल करता है.

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

यहां joinCustomAudience() के नतीजे को मैनेज करने का एक उदाहरण दिया गया है:

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

कस्टम ऑडियंस से ऑप्ट आउट करना

अगर कोई उपयोगकर्ता, कस्टम ऑडियंस के लिए कारोबार की ज़रूरी शर्तों को पूरा नहीं करता है, तो ऐप्लिकेशन या SDK टूल, leaveCustomAudience() को कॉल करके डिवाइस से कस्टम ऑडियंस को हटा सकता है. यूनीक पैरामीटर के आधार पर, किसी CustomAudience को हटाने के लिए, यह तरीका अपनाएं:

1. CustomAudienceManager ऑब्जेक्ट को शुरू करें.
2. कस्टम ऑडियंस के buyer और name की मदद से, LeaveCustomAudienceRequest को शुरू करें. इन इनपुट फ़ील्ड के बारे में ज़्यादा जानने के लिए, "कस्टम ऑडियंस में शामिल होना" लेख पढ़ें.
3. LeaveCustomAudienceRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ, एसिंक्रोनस leaveCustomAudience() तरीके को कॉल करें.

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

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

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

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() को कॉल करने की तरह ही, OutcomeReceiver से एपीआई कॉल के खत्म होने का सिग्नल मिलता है. निजता की सुरक्षा के लिए, गड़बड़ी के नतीजे में यह नहीं बताया जाता कि गड़बड़ी अंदरूनी है या अमान्य आर्ग्युमेंट की वजह से हुई है. एपीआई कॉल पूरा होने पर, onResult() कॉलबैक को कॉल किया जाता है. भले ही, मैच करने वाली कस्टम ऑडियंस को हटाया गया हो या नहीं.

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

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

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

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

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

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

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

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

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

selectAds() तरीके के लिए AdSelectionConfig इनपुट की ज़रूरत होती है. इसमें आपको ये ज़रूरी पैरामीटर देने होंगे:

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

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

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

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

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

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

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

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

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

ऐप्लिकेशन में कॉन्टेक्स्ट के हिसाब से विज्ञापन दिखाने के लिए, टारगेट ऐप्लिकेशन को ContextualAds ऑब्जेक्ट बनाना होगा:

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

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

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

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

ऐप्लिकेशन इंस्टॉल करने का बढ़ावा देने वाले विज्ञापन फ़िल्टर करना

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

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

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

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

अगला चरण, पब्लिशर ऐप्लिकेशन में विज्ञापन फ़िल्टर करने की सुविधा सेट अप करना है. पब्लिशर ऐप्लिकेशन में विज्ञापन दिखाने वाली पार्टी (ज़्यादातर मामलों में, यह सप्लाई-साइड SDK होता है) को अपने AdFilters ऑब्जेक्ट को इस बारे में जानकारी देनी होगी कि उसे ऐप्लिकेशन से जुड़े कौनसे विज्ञापन फ़िल्टर करने हैं:

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

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

मांग पूरी करने वाले पब्लिशर, अपनी पसंद के मुताबिक बनाए गए ऑडियंस सेगमेंट में मौजूद विज्ञापनों के लिए भी AdFilter सेट कर सकते हैं.

AdFilters को नया AdData ऑब्जेक्ट बनाते समय भी पास किया जा सकता है:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

फ़्रीक्वेंसी कैप फ़िल्टर करना

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

फ़्रीक्वेंसी कैप फ़िल्टर के दो मुख्य कॉम्पोनेंट होते हैं: विज्ञापन इवेंट टाइप और विज्ञापन काउंटर की. विज्ञापन इवेंट के ये टाइप इस्तेमाल किए जा सकते हैं:

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

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

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

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

नीलामी में फ़्रीक्वेंसी कैपिंग का इस्तेमाल करने के लिए, आपको सबसे पहले KeyedFrequencyCap ऑब्जेक्ट बनाने होंगे:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

KeyedFrequencyCap ऑब्जेक्ट बनाने के बाद, उन्हें AdFilters ऑब्जेक्ट में पास किया जा सकता है.

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

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

जब AdFilters ऑब्जेक्ट में फ़्रीक्वेंसी कैप फ़िल्टर भर दिए जाते हैं, तो कस्टम ऑडियंस बनाते समय इसे पास किया जा सकता है:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

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

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

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

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

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

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

तीसरे पक्ष के नेटवर्क

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

• विज्ञापन चुनने की सुविधा का इस्तेमाल करना
• रिपोर्ट पर मिले इंप्रेशन

यहां मीडिएशन नेटवर्क अडैप्टर का एक उदाहरण दिया गया है:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

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

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

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

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

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

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

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

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

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

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

AdSelectionFromOutcomesConfig बनाना

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

मीडिएशन नेटवर्क, पिछले सेक्शन से मिले 1P AdSelectionId और 3P नेटवर्क के लिए तय किए गए बिड फ़्लोर का इस्तेमाल करके AdSelectionFromOutcomesConfig बनाते हैं. मीडिएशन चेन के हर चरण के लिए, एक नया AdSelectionFromOutcomesConfig बनाया जाना चाहिए.

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

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

    return adSelectionClient.selectAds(config){}
}

वॉटरफ़ॉल मीडिएशन के लिए, selectAds() तरीके को ओवरराइड करने के लिए AdSelectionFromOutcomesConfig इनपुट की ज़रूरत होती है. इसमें आपको ये ज़रूरी पैरामीटर देने होंगे:

• सेलर: विज्ञापन दिखाने वाले सेलर के विज्ञापन नेटवर्क का आइडेंटिफ़ायर. यह विज्ञापन चुनने की प्रोसेस शुरू करता है.
• AdSelectionIds: यह 1P विज्ञापन के लिए, पिछली selectAds() प्रोसेस के सिंगलटन की सूची होती है.
• विज्ञापन चुनने के सिग्नल: यह एक JSON ऑब्जेक्ट होता है. इसे स्ट्रिंग के तौर पर क्रम से लगाया जाता है. इसमें ऐसे सिग्नल होते हैं जिनका इस्तेमाल खरीदार की बिडिंग लॉजिक में किया जाता है. इस मामले में, दिए गए तीसरे पक्ष के नेटवर्क के लिए, बिड फ़्लोर शामिल करें.
• विज्ञापन चुनने के लॉजिक का यूआरआई: यह एक एचटीटीपीएस यूआरएल होता है. विज्ञापन चुनने के दौरान, इस यूआरएल से क्वेरी की जाती है, ताकि मीडिएशन नेटवर्क का JavaScript कोड फ़ेच किया जा सके. इस कोड का इस्तेमाल, सबसे अच्छा परफ़ॉर्म करने वाले विज्ञापन को चुनने के लिए किया जाता है. इस JavaScript में ज़रूरी फ़ंक्शन सिग्नेचर देखें. अगर बिड, बिड फ़्लोर से ज़्यादा है, तो JavaScript को 3P विज्ञापन दिखाना चाहिए. अगर बिड, बिड फ़्लोर से कम है, तो JavaScript को null दिखाना चाहिए. इससे मीडिएशन SDK, मीडिएशन चेन को छोटा कर सकता है. ऐसा तब होता है, जब कोई विज्ञापन नेटवर्क सबसे ज़्यादा बिड जीत जाता है.

AdSelectionOutcomesConfig बनाने के बाद, चेन में सबसे पहले मौजूद 3P नेटवर्क के selectAds() तरीके को कॉल करें.

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

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

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

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

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

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

वॉटरफ़ॉल मीडिएशन को व्यवस्थित करना

मीडिएशन की प्रोसेस को पूरा करने के लिए, यहां कार्रवाइयों का क्रम दिया गया है.

1. पहली पार्टी के विज्ञापन चुनने की सुविधा का इस्तेमाल करें.
2. मीडिएशन चेन को दोहराएं. हर तीसरे पक्ष के नेटवर्क के लिए, यह तरीका अपनाएं:
   1. AdSelectionFromOutcomeConfig बनाएं. इसमें 1P outcomeId और 3P एसडीके का बिड फ़्लोर शामिल है.
   2. पिछले चरण के कॉन्फ़िगरेशन के साथ selectAds() को कॉल करें.
   3. अगर नतीजा खाली नहीं है, तो विज्ञापन दिखाएं.
   4. मौजूदा एसडीके नेटवर्क अडैप्टर के selectAds() तरीके को कॉल करें. अगर नतीजा खाली नहीं है, तो विज्ञापन दिखाएं.
3. अगर चेन में कोई भी विज्ञापन नहीं चुना जाता है, तो 1P विज्ञापन दिखाएं.

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

विज्ञापन इंप्रेशन की रिपोर्ट

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

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

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

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

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

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

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

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

इन ज़रूरी पैरामीटर की मदद से, ReportImpressionRequest को शुरू करें:

• विज्ञापन चुनने का आईडी: यह आईडी सिर्फ़ डिवाइस के उपयोगकर्ता के लिए यूनीक होता है. इससे विज्ञापन के चुने जाने की पुष्टि होती है.
• विज्ञापन चुनने का कॉन्फ़िगरेशन: यह वही कॉन्फ़िगरेशन है जिसका इस्तेमाल selectAds() कॉल में किया गया था. इसकी पहचान, दिए गए विज्ञापन चुनने के आईडी से होती है.

एसिंक्रोनस reportImpression() तरीका, एपीआई कॉल के नतीजे के बारे में बताने के लिए OutcomeReceiver ऑब्जेक्ट का इस्तेमाल करता है.

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

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

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

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

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 API की मदद से, रेंडर किए गए विज्ञापन के लिए ज़्यादा जानकारी वाले इंटरैक्शन की रिपोर्ट की जा सकती है. इसमें व्यू टाइम, क्लिक, होवर या कोई अन्य काम की मेट्रिक शामिल हो सकती है, जिसे इकट्ठा किया जा सकता है. ये रिपोर्ट पाने के लिए, आपको दो चरण पूरे करने होंगे. सबसे पहले, खरीदारों और सेलर को इन रिपोर्ट को पाने के लिए, अपनी रिपोर्टिंग 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 फ़ंक्शन में रजिस्टर किया था.
• इंटरैक्शन डेटा: यह एक स्ट्रिंग होती है. इसमें वह डेटा शामिल होता है जिसे इवेंट रिपोर्ट में शामिल करना होता है. इस डेटा को रिपोर्टिंग सर्वर पर वापस पोस्ट किया जाता है.
• रिपोर्टिंग डेस्टिनेशन: यह एक बिट मास्क है. इससे यह पता चलता है कि इवेंट की जानकारी खरीदार, विक्रेता या दोनों को देनी है. ये फ़्लैग, प्लैटफ़ॉर्म से मिलते हैं. साथ ही, बिटवाइज़ ऑपरेशन का इस्तेमाल करके फ़ाइनल डेस्टिनेशन मास्क बनाया जा सकता है. किसी एक प्लैटफ़ॉर्म पर शिकायत करने के लिए, सीधे तौर पर प्लैटफ़ॉर्म से मिले फ़्लैग का इस्तेमाल किया जा सकता है. एक से ज़्यादा डेस्टिनेशन को रिपोर्ट करने के लिए, बिटवाइज़ OR (|) का इस्तेमाल करके फ़्लैग वैल्यू को एक साथ जोड़ा जा सकता है.

एसिंक्रोनस reportInteraction() तरीका, एपीआई कॉल के नतीजे के बारे में बताने के लिए OutcomeReceiver ऑब्जेक्ट का इस्तेमाल करता है.

• onResult() कॉलबैक से पता चलता है कि रिपोर्ट इंटरैक्शन कॉल मान्य है.
• onError() कॉलबैक से, इन संभावित स्थितियों के बारे में पता चलता है:
  • अगर ऐप्लिकेशन के बैकग्राउंड में चलने के दौरान कॉल किया जाता है, तो गड़बड़ी की जानकारी के साथ IllegalStateException दिखता है.
  • अगर क्लाइंट को reportInteraction() को कॉल करने से रोका जाता है, तो LimitExceededException वापस कर दिया जाता है.
  • अगर पैकेज को निजता बनाए रखने वाले एपीआई को कॉल करने के लिए रजिस्टर नहीं किया गया है, तो SecurityException() वैल्यू मिलती है.
  • अगर इंटरैक्शन की रिपोर्टिंग करने वाला ऐप्लिकेशन, selectAds() को कॉल करने वाले ऐप्लिकेशन से अलग है, तो IllegalStateException वापस भेज दिया जाता है.
• अगर उपयोगकर्ता ने Privacy Sandbox API चालू करने की सहमति नहीं दी है, तो कॉल साइलेंट मोड में फ़ेल हो जाएगा.

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

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

इंटरैक्शन रिपोर्टिंग की सुविधा

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

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

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

• उपयोगकर्ता के बिडिंग सिग्नल
• भरोसेमंद बिडिंग डेटा
• 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 में ये फ़ंक्शन शामिल होने चाहिए:

• generateBid()
• reportWin()

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

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

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

• ad: यह 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 epoch के बाद के सेकंड के तौर पर दिखाया जाता है
  • ca_user_bidding_signals, JSON स्ट्रिंग है. इसे CustomAudience के userBiddingSignals फ़ील्ड में, खाता बनाते समय सेट किया जाता है
  • trusted_bidding_signals, contextual_signals और user_signals, JSON ऑब्जेक्ट हैं. इन्हें खाली ऑब्जेक्ट के तौर पर पास किया जाता है. इन्हें आने वाले समय में रिलीज़ किया जाएगा. इनका फ़ॉर्मैट, प्लैटफ़ॉर्म लागू नहीं करता है. इन्हें विज्ञापन टेक्नोलॉजी कंपनी मैनेज करती है.

नतीजा:

• ad: वह विज्ञापन है जिसके लिए बिड की गई है. स्क्रिप्ट को, मिले हुए विज्ञापन की कॉपी को अलग मेटाडेटा के साथ वापस भेजने की अनुमति होती है. विज्ञापन की render_url प्रॉपर्टी में कोई बदलाव नहीं किया जाना चाहिए.
• bid: यह फ़्लोट वैल्यू है, जो इस विज्ञापन के लिए बिड वैल्यू को दिखाती है
• status: यह एक पूर्णांक वैल्यू होती है. यह वैल्यू इनमें से कोई भी हो सकती है:
  • 0: बदलाव लागू करने के लिए
  • 1: अगर कोई भी इनपुट सिग्नल अमान्य है, तो (या कोई भी ऐसी वैल्यू जो शून्य न हो). अगर generate-bid फ़ंक्शन, शून्य से अलग कोई वैल्यू दिखाता है, तो सभी सीए विज्ञापनों के लिए बिडिंग की प्रोसेस अमान्य हो जाती है

scoreAd()

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

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

• ad: generateBid दस्तावेज़ देखें
• bid: विज्ञापन के लिए बिड वैल्यू

• ad_selection_config: यह एक JSON ऑब्जेक्ट है. यह selectAds API के AdSelectionConfig पैरामीटर को दिखाता है. इसका फ़ॉर्मैट यह है:

  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 ऑब्जेक्ट. इन्हें खाली ऑब्जेक्ट के तौर पर पास किया जाता है. आने वाले समय में रिलीज़ होने वाले वर्शन में, इन्हें भरा जाएगा. इनके फ़ॉर्मैट को प्लैटफ़ॉर्म लागू नहीं करता है. इन्हें AdTech मैनेज करता है.

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

आउटपुट:

• 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: सबसे अच्छा परफ़ॉर्म करने वाले विज्ञापन का रेंडर यूआरएल
• bid: जीतने वाले विज्ञापन के लिए ऑफ़र की गई बिड
• contextual_signals: generateBid का दस्तावेज़ देखें

आउटपुट:

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

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

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

waterfall-mediation-truncation पहले से बनाया गया यूआरआई, JavaScript उपलब्ध कराता है. यह JavaScript, वॉटरफ़ॉल मीडिएशन के लॉजिक को लागू करती है. इसमें JavaScript, पहली पार्टी का विज्ञापन तब दिखाती है, जब 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 repo में, 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() तरीके को कॉल करें.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

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

विज्ञापन चुनने के दौरान इस्तेमाल की गई JavaScript को ओवरराइड करने के लिए, decisionLogicJs में सेलर-साइड के सही फ़ंक्शन सिग्नेचर होने चाहिए. JavaScript फ़ाइल को स्ट्रिंग के तौर पर पढ़ने का उदाहरण देखने के लिए, GitHub पर Protected Audience API का सैंपल ऐप्लिकेशन देखें.

एसिंक्रोनस overrideAdSelectionConfigRemoteInfo() तरीका, एपीआई कॉल के नतीजे के बारे में बताने के लिए OutcomeReceiver ऑब्जेक्ट का इस्तेमाल करता है.

onResult() कॉलबैक से पता चलता है कि ओवरराइड करने की सुविधा सही तरीके से लागू हो गई है. selectAds() को किए जाने वाले आने वाले कॉल में, फ़ैसले लेने और रिपोर्टिंग के लिए उसी लॉजिक का इस्तेमाल किया जाएगा जिसे आपने ओवरराइड के तौर पर पास किया है.

onError() कॉलबैक से दो संभावित स्थितियों के बारे में पता चलता है:

• अगर अमान्य तर्कों के साथ ओवरराइड करने की कोशिश की जाती है, तो AdServiceException, IllegalArgumentException को वजह के तौर पर दिखाता है.
• अगर डीबग मोड में नहीं चल रहे किसी ऐसे ऐप्लिकेशन के साथ ओवरराइड करने की कोशिश की जाती है जिसमें डेवलपर के विकल्प चालू हैं, तो AdServiceException, IllegalStateException को वजह के तौर पर दिखाता है.

सेलर साइड से किए गए बदलावों को रीसेट करें

इस सेक्शन में यह माना गया है कि आपने सेलर साइड की JavaScript को बदल दिया है. साथ ही, आपके पास पिछले सेक्शन में इस्तेमाल किए गए TestAdSelectionManager और AdSelectionConfig का रेफ़रंस है.

सभी AdSelectionConfigs के लिए, बदलावों को रीसेट करने के लिए:

1. काम के OutcomeReceiver ऑब्जेक्ट के साथ, एसिंक्रोनस resetAllAdSelectionConfigRemoteOverrides() तरीके को कॉल करें.

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

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

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

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

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

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

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

खरीदार और नाम के लिए इस्तेमाल की गई वैल्यू वही हैं जिनका इस्तेमाल कस्टम ऑडियंस बनाने के लिए किया गया था. इन फ़ील्ड के बारे में ज़्यादा जानें.

इसके अलावा, दो और पैरामीटर तय किए जा सकते हैं:

• biddingLogicJs: यह JavaScript, खरीदार के लॉजिक को सेव करती है. इसका इस्तेमाल विज्ञापन चुनने के दौरान किया जाता है. इस JavaScript में, ज़रूरी फ़ंक्शन सिग्नेचर देखें.
• trustedBiddingSignals: विज्ञापन चुनते समय इस्तेमाल किए जाने वाले बिडिंग सिग्नल. जांच के लिए, इसे खाली स्ट्रिंग के तौर पर इस्तेमाल किया जा सकता है.

एसिंक्रोनस overrideCustomAudienceRemoteInfo() तरीका, एपीआई कॉल के नतीजे के बारे में बताने के लिए OutcomeReceiver ऑब्जेक्ट का इस्तेमाल करता है.

onResult() कॉलबैक से पता चलता है कि ओवरराइड करने की सुविधा सही तरीके से लागू हो गई है. selectAds() को किए गए बाद के कॉल में, बिडिंग और रिपोर्टिंग के उस लॉजिक का इस्तेमाल किया जाता है जिसे आपने ओवरराइड के तौर पर पास किया है.

onError() कॉलबैक से दो संभावित स्थितियों के बारे में पता चलता है.

• अगर अमान्य तर्कों के साथ ओवरराइड करने की कोशिश की जाती है, तो AdServiceException, IllegalArgumentException को वजह के तौर पर दिखाता है.
• अगर डीबग मोड में नहीं चल रहे किसी ऐसे ऐप्लिकेशन के साथ ओवरराइड करने की कोशिश की जाती है जिसमें डेवलपर के विकल्प चालू हैं, तो AdServiceException, IllegalStateException को वजह के तौर पर दिखाता है.

खरीदारी करने वाले पक्ष की ओर से किए गए बदलावों को रीसेट करें

इस सेक्शन में यह माना गया है कि आपने खरीदारी करने वाले पक्ष की JavaScript को बदल दिया है. साथ ही, आपके पास पिछले सेक्शन में इस्तेमाल किए गए TestCustomAudienceManager का रेफ़रंस है.

सभी कस्टम ऑडियंस के लिए, ओवरराइड की गई सेटिंग को रीसेट करने के लिए:

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

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

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

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

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

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

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

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

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

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

सीमाएं

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

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

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