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

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


सुझाव, शिकायत या राय दें

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

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

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

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

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

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

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

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

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

      adb shell device_config put adservices ppapi_app_allow_list \"*\"
    
  4. अपने ऐप्लिकेशन मेनिफ़ेस्ट में ACCESS_ADSERVICES_CUSTOM_AUDIENCE अनुमति शामिल करें:

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
    
  5. अपने मेनिफ़ेस्ट के <application> एलिमेंट में विज्ञापन सेवाओं से जुड़े कॉन्फ़िगरेशन का रेफ़रंस दें:

      <property android:name="android.adservices.AD_SERVICES_CONFIG"
                android:resource="@xml/ad_services_config" />
    
  6. अपने मेनिफ़ेस्ट में विज्ञापन सेवाओं के एक्सएमएल रिसॉर्स के बारे में बताएं, जैसे कि res/xml/ad_services_config.xml. विज्ञापन सेवाओं की अनुमतियों और SDK टूल के ऐक्सेस कंट्रोल के बारे में ज़्यादा जानें.

      <ad-services-config>
        <custom-audiences allowAllToAccess="true" />
      </ad-services-config>
    
  7. डिफ़ॉल्ट रूप से, Ad Selection API किसी नीलामी या इंप्रेशन रिपोर्टिंग स्क्रिप्ट से बांटी जा सकने वाली ज़्यादा से ज़्यादा मेमोरी की सीमा लागू करता है. मेमोरी सीमित करने की सुविधा के लिए वेबव्यू 105.0.5195.58 या इसके बाद वाले वर्शन की ज़रूरत होती है. प्लैटफ़ॉर्म, वर्शन की जांच लागू करता है और selectAds और reportImpression एपीआई को कॉल नहीं कर पाता है. इसे सेट अप करने के दो विकल्प हैं:

    • विकल्प 1: इस जांच को बंद करने के लिए, इस 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() को कॉल करें.

Kotlin

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

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

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

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

Java

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

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

Java

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

में शामिल हो चुके कस्टमऑडियंस() के नतीजों को मैनेज करना

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

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

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

Kotlin

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

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

Java

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

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

पसंद के मुताबिक दर्शक छोड़ें

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

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

Kotlin

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

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

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

Java

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

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

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

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

विज्ञापन चुनने का विकल्प चलाएं

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

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

Kotlin

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

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

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

Java

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

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

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

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

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

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

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

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

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

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

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

काम के विज्ञापन

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

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

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

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

Java

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

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

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

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

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

Kotlin

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

Java

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

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

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

Kotlin

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

Java

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

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

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

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

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

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

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

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

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

Kotlin

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

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

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

Java

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

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

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

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

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

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

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

फ़िलहाल, प्राइवसी सैंडबॉक्स प्लैटफ़ॉर्म में पहले से बने यूआरआई के लिए, सिर्फ़ बुनियादी रिपोर्टिंग 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 टूल मीडिएशन नेटवर्क, तीसरे पक्ष के कई SDK टूल (3P नेटवर्क) को व्यवस्थित करें. वॉटरफ़ॉल मीडिएशन, इसी तरह की तरह काम करता है, भले ही नीलामी डिवाइस पर हुई हो या बिडिंग और नीलामी सेवाओं (B&A) पर चलाई गई हो.

3P नेटवर्क

3P नेटवर्क को ऐसा अडैप्टर देना ज़रूरी होता है जिससे मीडिएशन नेटवर्क, नीलामी चलाने के लिए ज़रूरी तरीके लागू कर सके:

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

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

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

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

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

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

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

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

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

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

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

विज्ञापन चुनने का विकल्प चलाएं

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

AdSelectionFromresultssConfig बनाना

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

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

Kotlin

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

Java

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

    return adSelectionClient.selectAds(config){}
}

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

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

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

Kotlin

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

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

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

Java

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

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

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

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

मीडिएशन प्रोसेस से जुड़ी कार्रवाइयों का क्रम नीचे दिया गया है.

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

Kotlin

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

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

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

Java

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

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

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

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

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

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

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

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

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

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

Java

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

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

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

Kotlin

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

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

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

नीचे दिए गए ज़रूरी पैरामीटर के साथ ReportImpressionRequest को शुरू करें:

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

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

  • onResult() कॉलबैक से पता चलता है कि इंप्रेशन रिपोर्टिंग के यूआरएल बनाए गए हैं और अनुरोध शेड्यूल किया गया है या नहीं.
  • 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 को फ़ेच किया जा सके. इस 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)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

इंटरैक्शन इवेंट की रिपोर्टिंग

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

  1. किसी AdSelectionManager ऑब्जेक्ट को शुरू करें.
  2. विज्ञापन चुनने का आईडी, इंटरैक्शन की, इंटरैक्शन डेटा, और रिपोर्टिंग डेस्टिनेशन के साथ एक ReportInteractionRequest ऑब्जेक्ट बनाएं.
  3. एसिंक्रोनस reportInteraction() तरीके को request ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ कॉल करें.
AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

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

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

नीचे दिए गए ज़रूरी पैरामीटर के साथ ReportInteractionRequest को शुरू करें:

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

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

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

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

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

सबसे अच्छी प्रोसेस वाली इंटरैक्शन रिपोर्टिंग

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

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

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

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

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

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

उदाहरण: बैकग्राउंड में हर दिन के अपडेट के लिए JSON का रिस्पॉन्स

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

विज्ञापन चुनने के लिए JavaScript

विज्ञापन चुनने का वर्कफ़्लो, खरीदार और विक्रेता से मिले JavaScript को लागू करता है.

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

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

बिड जनरेट करें()

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

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

  • ad: एक JSON ऑब्जेक्ट, जिसका फ़ॉर्मैट var ad = { 'render_url': url, 'metadata': json_metadata }; है
  • auction_signals, per_buyer_signals: नीलामी के कॉन्फ़िगरेशन ऑब्जेक्ट में मौजूद JSON ऑब्जेक्ट
  • custom_audience_bidding_signals: प्लैटफ़ॉर्म से जनरेट हुआ JSON ऑब्जेक्ट. इस JSON ऑब्जेक्ट का फ़ॉर्मैट यह है:

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

    कहां:

    • owner, buyer, और name ऐसी प्रॉपर्टी से ली गई स्ट्रिंग हैं जिनका नाम विज्ञापन चुनने में हिस्सा लेने वाली कस्टम ऑडियंस के नाम से ही है
    • activation_time और expiration_time कस्टम ऑडियंस के चालू होने और खत्म होने का समय है. इसे Unix Epoch के बाद से सेकंड के तौर पर दिखाया जाता है
    • ca_user_bidding_signals एक JSON स्ट्रिंग है, जिसे CustomAudience बनाते समय userBiddingSignals फ़ील्ड में बताया जाता है
    • trusted_bidding_signals, contextual_signals और user_signals, JSON ऑब्जेक्ट हैं. इन्हें खाली ऑब्जेक्ट के तौर पर पास किया जाता है और इन्हें आने वाले समय में रिलीज़ किया जाता है. उनका फ़ॉर्मैट, प्लैटफ़ॉर्म लागू नहीं करता और उसे विज्ञापन टेक्नोलॉजी मैनेज करती है.

नतीजा:

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

स्कोरविज्ञापन()

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

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

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

  • 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: ऐसा यूआरएल जिसका इस्तेमाल प्लैटफ़ॉर्म, खरीदार को इंप्रेशन की सूचना देने के लिए करता है

रिपोर्टWin()

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(
  interaction_key,
  reporting_uri
)

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

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

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

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

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

Java

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

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

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

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

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

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

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

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

onError() कॉलबैक दो संभावित स्थितियों को दिखाता है:

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

बिक्री पक्ष के बदलावों को रीसेट करें

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

सभी AdSelectionConfigs के लिए, ओवरराइड रूल रीसेट करने के लिए:

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

Kotlin

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

Java

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

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

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

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

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

Kotlin

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

// Join custom audience

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

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

Java

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

// Join custom audience

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

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

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

इसके अलावा, आपके पास दो और पैरामीटर बताने का विकल्प है:

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

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

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

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

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

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

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

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

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

Kotlin

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

Java

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

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

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

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

10

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

40 बाइट

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

64 केबी

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

बग और समस्याओं की रिपोर्ट करें

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