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

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

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

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

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

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

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

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

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

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

1. Android पर प्राइवसी सैंडबॉक्स के लिए, अपना डेवलपमेंट एनवायरमेंट सेट अप करें.
2. इसके लिए, ऐसे डिवाइस पर सिस्टम इमेज इंस्टॉल करें जिस पर यह सुविधा काम करती है या ऐसा एम्युलेटर सेट अप करें जिसमें Android पर प्राइवसी सैंडबॉक्स के साथ काम करने की सुविधा शामिल हो.

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 से वेबव्यू बीटा इंस्टॉल करें. यह वर्शन, पहले बताए गए वर्शन के बराबर या उससे ज़्यादा होना चाहिए.

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

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

1. CustomAudienceManager ऑब्जेक्ट को शुरू करें.
2. खरीदार के पैकेज और काम के नाम जैसे मुख्य पैरामीटर तय करके, CustomAudience ऑब्जेक्ट बनाएं. इसके बाद, JoinCustomAudienceRequest ऑब्जेक्ट को CustomAudience ऑब्जेक्ट से शुरू करें.
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 फ़ंक्शन में इनका इस्तेमाल करना आसान हो जाता है.
• भरोसेमंद बिडिंग डेटा: विज्ञापन चुनने की प्रोसेस के दौरान इस्तेमाल किया जाने वाला एचटीटीपीएस यूआरएल और स्ट्रिंग की सूची. यह सूची, भरोसेमंद कुंजी/वैल्यू सेवा से बिडिंग सिग्नल फ़ेच करती है.
• विज्ञापन: विज्ञापन चुनने में शामिल विज्ञापनों से जुड़े 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() callback को कॉल किया जाता है. भले ही, मैच करने वाली कस्टम ऑडियंस को हटाया गया हो या नहीं.

विज्ञापन चुनना शुरू करें

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Protected Audience, 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();

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

// 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 भी सेट कर सकते हैं जो उनकी कस्टम ऑडियंस में मौजूद होते हैं.

कोई नया AdData ऑब्जेक्ट इंस्टैंशिएट करते समय भी AdFilters को पास किया जा सकता है:

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

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

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

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

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

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

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

3P नेटवर्क

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

• विज्ञापन चुनना शुरू करें
• रिपोर्ट इंप्रेशन

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

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

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

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

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

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

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

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

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

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

विज्ञापन चुनना शुरू करें

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

एक AdSelectionFromresultssConfig बनाएं

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

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

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

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

    return adSelectionClient.selectAds(config){}
}

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

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

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

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

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

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

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

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

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

ऑर्केस्ट्रेट वॉटरफ़ॉल मीडिएशन

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

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

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

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

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

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

एसएसपी, 3P (तीसरे पक्ष का) SDK टूल के इस उदाहरण का इस्तेमाल, एक प्रोटोटाइप के तौर पर कर सकते हैं. इससे वे मीडिएशन फ़्लो में शामिल होने का तरीका जान सकेंगे:

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

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

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

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

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

• एपीआई, कस्टम ऑडियंस में दिए गए बिडिंग लॉजिक यूआरएल का इस्तेमाल करके, खरीदार से मिले उस 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. एसिंक्रोनस reportInteraction() तरीके को request ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ कॉल करें.

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

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

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

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

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

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

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

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

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

इंटरैक्शन रिपोर्टिंग के लिए सबसे सही तरीका

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 में ये फ़ंक्शन शामिल होने चाहिए:

• generateBid()
• reportWin()

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

नतीजा:

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

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: एक 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: इवेंट की रिपोर्ट पाने के लिए यूआरआई. यह, रिपोर्ट किए जा रहे इवेंट टाइप के हिसाब से होना चाहिए. इवेंट के साथ रिपोर्ट किए गए किसी भी डेटा को मैनेज करने के लिए, इसे एक पोस्ट अनुरोध स्वीकार करना होगा.

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

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

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. काम पूरा होने के बाद सूचना देने वाले resetAllAdSelectionConfigRemoteOverrides() तरीके को, काम के OutcomeReceiver ऑब्जेक्ट के साथ कॉल करें.

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

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

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

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

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

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

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

// Join custom audience

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

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

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

// Join custom audience

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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