एक सेलर के साथ, ब्राउज़र के आधार पर नीलामी करना

इस दस्तावेज़ में, आपको किसी एक सेलर के लिए, Protected Audience डेटा की मदद से नीलामी चलाने के बारे में खास जानकारी मिलेगी. इस जानकारी का इस्तेमाल, Protected Audience API के मौजूदा वर्शन में किया जाता है. किसी एक विक्रेता वाली नीलामी को कई विक्रेताओं को शामिल करने वाली ज़्यादा जटिल नीलामी के हिस्से के तौर पर चलाया जा सकता है. इस मामले में, एक सेलर नीलामी को "कॉम्पोनेंट ऑक्शन" कहा जाता है. इससे "टॉप लेवल नीलामी" में विज्ञापन के उम्मीदवारों के लिए, कई सेलर हिस्सा ले सकते हैं.

Protected Audience API की पूरी लाइफ़साइकल के बारे में जानने के लिए, डेवलपर गाइड पढ़ें. साथ ही, सेलर के डिवाइस पर नीलामी को चलाने के तरीके के बारे में गहराई से जानकारी पाने के लिए, Protected Audience API के बारे में जानकारी लेख पढ़ें.

Protected Audience API की विज्ञापन नीलामी के छह चरण

Protected Audience API की विज्ञापन नीलामी के छह स्टेज
इस डायग्राम में, Protected Audience API विज्ञापन नीलामी के हर चरण को दिखाया गया है.
  1. कोई उपयोगकर्ता किसी ऐसी साइट पर जाता है जो विज्ञापन दिखाती है.
  2. सेलर का कोड, navigator.runAdAuction() लागू करता है. इससे पता चलता है कि कौनसा विज्ञापन स्पेस बिक्री के लिए है और कौन बिडिंग कर सकता है. विक्रेताओं को एक ऐसी स्क्रिप्ट भी शामिल करनी होगी जो हर बोली, scoreAd() को स्कोर देती है.
  3. न्योता पाने वाले खरीदार का कोड, बिड जनरेट करने, काम के विज्ञापन क्रिएटिव का यूआरएल, और अन्य डेटा जनरेट करता है. बिडिंग स्क्रिप्ट, खरीदार की कुंजी/वैल्यू सेवा से रीयल-टाइम डेटा के लिए क्वेरी कर सकती है, जैसे कि विज्ञापन कैंपेन का बाकी बजट.
  4. सेलर का कोड, हर बिड के लिए स्कोर तय करता है और विजेता चुनता है. यह लॉजिक, बिड की वैल्यू का इस्तेमाल करता है और अन्य डेटा, बिड को दिखाने के हिसाब से सही करता है. ऐसे विज्ञापन जो प्रासंगिक विनर को पछाड़ नहीं सकते. रीयल-टाइम डेटा के लिए, सेलर अपनी कुंजी/वैल्यू वाली सेवा का इस्तेमाल कर सकता है.
  5. जीतने वाले विज्ञापन को एक ओपेक वैल्यू के तौर पर दिखाया जाता है, जो फ़ेंस किए गए फ़्रेम में दिखता है. सेलर और पब्लिशर, दोनों इस वैल्यू को नहीं देख पाएंगे.
  6. नीलामी की सूचना, विक्रेता और जीतने वाले खरीदारों को दी जाती है.

जब कोई उपयोगकर्ता किसी विज्ञापन दिखाने वाले पेज पर जाता है, तब नीलामी हो सकती है. नीलामियां समय से पहले चलाई जा सकती हैं, ताकि विज्ञापन स्लॉट के दिखाई देने पर विज्ञापन क्रिएटिव तैयार हो जाए.

विक्रेता, विज्ञापन नीलामी शुरू करते हैं, scoreAd() फ़ंक्शन के तौर पर दिए गए कस्टम लॉजिक का इस्तेमाल करके उम्मीदवार के विज्ञापनों को स्कोर देते हैं, और नीलामी के नतीजों की जानकारी, अपने और जीतने वाले खरीदार को देने की ज़िम्मेदारी विक्रेता की होती है. विक्रेता, अपने scoreAd() फ़ंक्शन का इस्तेमाल करके, पब्लिशर के नियमों को लागू कर सकते हैं और विज्ञापन की क्वालिटी को फ़िल्टर भी कर सकते हैं.

विक्रेता के तौर पर ये चीज़ें हो सकती हैं:

  • कॉन्टेंट पब्लिशर, अपनी वेबसाइट पर विज्ञापन का कॉन्टेंट होस्ट करने के लिए खुद का इस्तेमाल करते हैं
  • सप्लाई-साइड प्लैटफ़ॉर्म (एसएसपी), जो विज्ञापन पब्लिशर के साथ काम करते हैं और अन्य सेवाएं देते हैं
  • तीसरे पक्ष की स्क्रिप्ट, जो विज्ञापन नीलामी में हिस्सा लेने के लिए पब्लिशर के साथ मिलकर काम करती हैं.

नीलामी चलाने की आवश्यकताएं

नीलामी चलाने के लिए, विक्रेता को दो JavaScript फ़ंक्शन की ज़रूरत होती है:

  • scoreAd(), जिसमें किसी विज्ञापन उम्मीदवार का स्कोर मिलता है
  • reportResult(), जो विक्रेता को नीलामी के नतीजे की जानकारी देता है

इन स्क्रिप्ट को सेलर के मालिकाना हक वाले एक ही एंडपॉइंट से दिखाया जाना चाहिए.

scoreAd()

विक्रेता को अपने मालिकाना हक वाले एंडपॉइंट से दिखाया जाने वाला scoreAd() फ़ंक्शन तय करना होगा. एंडपॉइंट को नीलामी कॉन्फ़िगरेशन में, decisionLogicUrl के तौर पर दिखाया गया है. scoreAd() फ़ंक्शन में यह हस्ताक्षर होता है:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

scoreAd() पैरामीटर हैं:

  • adMetaData, जो कि विज्ञापन क्रिएटिव के बारे में आर्बिट्रेरी मेटाडेटा है जो खरीदार से मिला है. यह JSON क्रम के मुताबिक बनाया जा सकने वाला ऑब्जेक्ट है. सेलर और खरीदारों को इसके स्ट्रक्चर को तय करना होगा और उससे सहमत होना होगा.
  • bid, जो बिड को दिखाने वाली संख्या है.
  • auctionConfig, नीलामी करने के लिए इस्तेमाल किया जाने वाला नीलामी कॉन्फ़िगरेशन है.
  • trustedScoringSignals, ये ऐसे सिग्नल होते हैं जिन्हें नीलामी के समय, विक्रेता के कुंजी/वैल्यू सर्वर से पढ़ा जाता है. यह प्लैटफ़ॉर्म इस लुकअप के लिए कुंजी के तौर पर, उम्मीदवार विज्ञापन के renderUrl का इस्तेमाल करेगा.
  • browserSignals, एक ऑब्जेक्ट है जिसे ब्राउज़र ने बनाया है. इसमें वह जानकारी शामिल होती है जिसके बारे में ब्राउज़र को पता है. साथ ही, इसमें वह जानकारी भी शामिल होती है जिसकी पुष्टि विक्रेता की नीलामी स्क्रिप्ट कर सकती है.
  • directFromSellerSignals एक ऑब्जेक्ट है, जिसमें ये फ़ील्ड हो सकते हैं: ** sellerSignals: auctionConfig.sellerSignals की तरह, लेकिन directFromSellerSignals तरीके का इस्तेमाल करके पास किया गया. ** auctionSignals: auctionConfig.auctionSignals की तरह, लेकिन directFromSellerSignals तरीके का इस्तेमाल करके पास किया गया.

browserSignals का एक उदाहरण नीचे दिया गया है. ध्यान दें कि उम्मीदवार विज्ञापन का renderUrl, इन सिग्नल के ज़रिए उपलब्ध है:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

सेलर को ऐसा reportResult() फ़ंक्शन तय करना होगा जो उसके मालिकाना हक वाले एंडपॉइंट से दिखाया जाए. एंडपॉइंट की जानकारी नीलामी कॉन्फ़िगरेशन में, decisionLogicUrl के तौर पर दी गई है. reportResult() फ़ंक्शन में ये हस्ताक्षर किए गए हैं:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

reportResult() पैरामीटर हैं:

  • auctionConfig, नीलामी करने के लिए इस्तेमाल किया जाने वाला नीलामी कॉन्फ़िगरेशन है.
  • browserSignals, एक ऑब्जेक्ट है जिसे ब्राउज़र ने बनाया है. इसमें वह जानकारी शामिल होती है जिसके बारे में ब्राउज़र को पता है. साथ ही, इसमें वह जानकारी भी शामिल होती है जिसकी पुष्टि विक्रेता की नीलामी स्क्रिप्ट कर सकती है. यह वही ऑब्जेक्ट है जिसे scoreAds() फ़ंक्शन को पास किया गया है.

reportResult(), signalsForWinner दिखाता है. यह एक आर्बिट्रेरी JSON ऑब्जेक्ट होता है, जिसे जीतने वाले खरीदार के रिपोर्टिंग फ़ंक्शन को पास किया जाता है. इसमें ऐसी सभी ज़रूरी जानकारी शामिल होनी चाहिए जो विक्रेता नीलामी के बारे में दे सकता है. यह जानकारी, खरीदार की रिपोर्टिंग के लिए ज़रूरी होती है.

Protected Audience API की नीलामी करना

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

  1. नीलामी कॉन्फ़िगर करें. इस चरण में, auctionConfig ऑब्जेक्ट बनाना शामिल है. इससे विक्रेता को यह बताने में मदद मिलती है कि किस खरीदार को नीलामी में हिस्सा लेना चाहिए. साथ ही, इससे सेलर को ऐसे सिग्नल मिलते हैं जो बिड जनरेट करने या विज्ञापन स्कोरिंग के दौरान काम के हो सकते हैं.
  2. navigator.runAdAuction() को कॉल करके नीलामी शुरू करें और पिछले चरण में बनाए गए कॉन्फ़िगरेशन को पास करें. इससे बिड जनरेट करने, फिर स्कोरिंग करने वाले खरीदारों की चेन शुरू होती है. इस चरण का नतीजा एक विज्ञापन कैंडिडेट होता है, जिसे विज्ञापन दिखाने के लिए रेंडर किया जा सकता है.
  3. फ़ेंस किए गए फ़्रेम या iframe में जीतने वाले विज्ञापन को रेंडर करें.
  4. नीलामी के नतीजे की रिपोर्ट करें. navigator.sendReportTo() एक फ़ंक्शन है, जो रिपोर्टिंग शुरू करेगा. सेलर को हमेशा नीलामी के नतीजों की रिपोर्ट मिलेगी. सिर्फ़ नीलामी जीतने वाले खरीदार को ही रिपोर्ट मिलेगी. यह अपने सर्वर को रिपोर्ट करने के लिए, इस गाइड में बताए गए विक्रेता के reportResult() का इस्तेमाल करता है.