सेलर एपीआई गाइड और Protected Audience API की विज्ञापन नीलामी के लिए रेफ़रंस.
इस लेख में, आपको विज्ञापन नीलामी का तकनीकी रेफ़रंस मिलेगा. इसका इस्तेमाल, Protected Audience API की मौजूदा टेस्टिंग में किया जाता है.
Protected Audience API की पूरी लाइफ़साइकल के बारे में जानने के लिए, डेवलपर गाइड पढ़ें. साथ ही, सेलर, डिवाइस पर नीलामी करने के तरीके के बारे में गहराई से जानने के लिए, Protected Audience API के बारे में जानकारी देखें.
क्या आप डेवलपर नहीं हैं? Protected Audience API की खास जानकारी पढ़ें.
Protected Audience API की विज्ञापन नीलामी क्या होती है?
Protected Audience API की विज्ञापन नीलामी, छोटे JavaScript प्रोग्राम का एक कलेक्शन है. ब्राउज़र, किसी विज्ञापन को चुनने के लिए उपयोगकर्ता के डिवाइस पर इन्हें चलाता है. निजता की सुरक्षा के लिए, विक्रेता और खरीदारों के सभी विज्ञापन नीलामी कोड एक अलग JavaScript वर्कलेट में चलाए जाते हैं, जिनसे बाहर के लोगों से बात नहीं की जा सकती.
- कोई उपयोगकर्ता किसी ऐसी साइट पर जाता है जो विज्ञापन दिखाती है.
- सेलर का कोड,
navigator.runAdAuction()
लागू करता है. इससे पता चलता है कि कौनसा विज्ञापन स्पेस बिक्री के लिए है और कौन बिडिंग कर सकता है. विक्रेताओं को एक ऐसी स्क्रिप्ट भी शामिल करनी होगी जो हर बोली,scoreAd()
को स्कोर देती है. - न्योता पाने वाले खरीदार का कोड, बिड जनरेट करने, काम के विज्ञापन क्रिएटिव का यूआरएल, और अन्य डेटा जनरेट करता है. बिडिंग स्क्रिप्ट, खरीदार की कुंजी/वैल्यू सेवा से रीयल-टाइम डेटा के लिए क्वेरी कर सकती है, जैसे कि विज्ञापन कैंपेन का बाकी बजट.
- सेलर का कोड, हर बिड के लिए स्कोर तय करता है और विजेता चुनता है. यह लॉजिक, बिड की वैल्यू का इस्तेमाल करता है और अन्य डेटा, बिड को दिखाने के हिसाब से सही करता है. ऐसे विज्ञापन जो प्रासंगिक विनर को पछाड़ नहीं सकते. रीयल-टाइम डेटा के लिए, सेलर अपनी कुंजी/वैल्यू वाली सेवा का इस्तेमाल कर सकता है.
- जीतने वाले विज्ञापन को एक ओपेक वैल्यू के तौर पर दिखाया जाता है, जो फ़ेंस किए गए फ़्रेम में दिखता है. सेलर और पब्लिशर, दोनों इस वैल्यू को नहीं देख पाएंगे.
- नीलामी की सूचना, विक्रेता और जीतने वाले खरीदारों को दी जाती है.
नीलामी कब होती है?
Protected Audience API को अपने हिसाब से या प्रोग्राम के हिसाब से, अपने-आप होने वाली नीलामियों के साथ चलाया जा सकता है. एक से ज़्यादा सेलर वाली, प्रोग्रामैटिक नीलामी में:
- उपयोगकर्ता, इस सुविधा में शामिल किसी साइट पर जाता है.
- एक उपलब्ध विज्ञापन स्लॉट के लिए प्रासंगिक विज्ञापन खोजने के लिए कोई अन्य विक्रेता नीलामी करता है.
- Protected Audience API की नीलामी हो रही है.
scoreAd()
खरीदार की बिड की तुलना पहली नीलामी के नतीजों से करता है.
प्रासंगिक विजेता को पछाड़ने वाली बोलियां अस्वीकार कर दी जाती हैं.
Protected Audience API की विज्ञापन नीलामी कौन चलाता है?
ऐसे कई पक्ष हैं जो विज्ञापन स्पेस को बेचने के लिए नीलामी कर सकते हैं.
उदाहरण के लिए:
- कॉन्टेंट पब्लिशर: अपनी वेबसाइट पर विज्ञापन का कॉन्टेंट होस्ट करने के लिए खुद की मदद करता है.
- सप्लाई-साइड प्लैटफ़ॉर्म (SSP): पब्लिशर के साथ काम करना और अन्य सेवाएं देना.
- तीसरे पक्ष की स्क्रिप्ट: विज्ञापन नीलामी में हिस्सा लेने के लिए, पब्लिशर की मदद करना.
Protected Audience API की मदद से, सेलर के पास तीन काम होते हैं:
- पब्लिशर के नियमों को लागू करने के लिए: कौनसे खरीदार और कौनसी बिड, लागू की जा सकती हैं.
- नीलामी के लॉजिक को चलाएं: हर बिड के लिए ज़रूरी स्कोर का हिसाब लगाने के लिए, JavaScript को वर्कलेट में चलाया जाता है.
- नीलामी के नतीजे की रिपोर्ट करें.
ये काम, विक्रेता के कोड में प्रोग्राम के ज़रिए तब किए जाते हैं, जब यह JavaScript फ़ंक्शन navigator.runAdAuction()
को कॉल करके कोई विज्ञापन नीलामी शुरू करता है.
एपीआई फ़ंक्शन
runAdAuction()
सेलर, उपयोगकर्ता के ब्राउज़र से navigator.runAdAuction()
को कॉल करके, विज्ञापन नीलामी शुरू करने का अनुरोध करता है.
उदाहरण के लिए:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
runAdAuction()
एक प्रॉमिस दिखाता है जो विज्ञापन नीलामी के नतीजे दिखाने वाले URN (urn:uuid:<something>
) में बदल जाता है. इसे ब्राउज़र सिर्फ़ तब डिकोड कर सकता है, जब इसे रेंडरिंग के लिए फ़ेंस किए गए फ़्रेम पर पास किया जाता है. ऐसा करने से, पब्लिशर पेज सबसे अच्छा परफ़ॉर्म करने वाले विज्ञापन की जांच नहीं कर सकता.
decisionLogicUrl
स्क्रिप्ट हर विज्ञापन, उससे जुड़ी बिड और मेटाडेटा के साथ-साथ, एक-एक करके उसका आकलन करती है. इसके बाद, उसे कोई न्यूमेरिक ' डिज़ायरेबिलिटी स्कोर' असाइन करती है.
auctionConfig
प्रॉपर्टी
seller
- ज़रूरी है
- उदाहरण:
'https://ssp.example'
- भूमिका: विक्रेता का ऑरिजिन.
decisionLogicUrl
- ज़रूरी है
- उदाहरण:
'https://ssp.example/auction-decision-logic.js'
- भूमिका: नीलामी के वर्कलेट की JavaScript के लिए यूआरएल.
trustedScoringSignalsUrl
- ज़रूरी नहीं
- उदाहरण:
'https://ssp.example/scoring-signals'
- भूमिका: विक्रेता के भरोसेमंद सर्वर का यूआरएल.
interestGroupBuyers
- ज़रूरी है
- उदाहरण:
['https://dsp.example', 'https://buyer2.example', ...]
- भूमिका: उन सभी इंटरेस्ट ग्रुप के मालिकों की ऑरिजिन जिन्होंने नीलामी में बिड करने के लिए कहा.
- ध्यान दें: सेलर, सभी इंटरेस्ट ग्रुप को बिडिंग की अनुमति देने के लिए,
interestGroupBuyers:
बता सकता है. इसके बाद, इंटरेस्ट ग्रुप के मालिक को शामिल करने के बजाय, किसी अन्य शर्त के आधार पर विज्ञापनों को स्वीकार या अस्वीकार किया जाता है. उदाहरण के लिए, अपनी नीतियों के अनुपालन की पुष्टि करने के लिए, विक्रेता विज्ञापन क्रिएटिव की समीक्षा कर सकता है. auctionSignals
- ज़रूरी नहीं
- उदाहरण:
{...}
- भूमिका: पेज के कॉन्टेक्स्ट, नीलामी के टाइप वगैरह के बारे में सेलर की जानकारी
sellerSignals
- ज़रूरी नहीं
- उदाहरण:
{...}
- भूमिका: पब्लिशर की सेटिंग पर आधारित जानकारी, कॉन्टेंट के हिसाब से विज्ञापन का अनुरोध करना वगैरह.
sellerTimeout
- ज़रूरी नहीं
- उदाहरण:
100
- भूमिका: विक्रेता की
scoreAd()
स्क्रिप्ट का ज़्यादा से ज़्यादा रनटाइम (ms). perBuyerSignals
- ज़रूरी नहीं
- उदाहरण:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- भूमिका: हर खरीदार के सर्वर से, उसके पेज के बारे में काम के सिग्नल.
perBuyerTimeouts
- ज़रूरी नहीं
- उदाहरण:
50
- भूमिका: किसी खरीदार की
generateBid()
स्क्रिप्ट का ज़्यादा से ज़्यादा रनटाइम (ms). componentAuctions
- ज़रूरी नहीं
- उदाहरण:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- भूमिका: कॉम्पोनेंट की नीलामियों के लिए अतिरिक्त कॉन्फ़िगरेशन.
decisionLogicUrl
decisionLogicUrl
, नीलामी कॉन्फ़िगरेशन ऑब्जेक्ट की एक प्रॉपर्टी है, जिसे
runAdAuction()
को पास किया गया है. इस यूआरएल में scoreAd()
फ़ंक्शन के लिए, एक स्क्रिप्ट शामिल होनी चाहिए. हर विज्ञापन के लिए इस लॉजिक को एक बार चलाया जाता है, ताकि यह तय किया जा सके कि विज्ञापन कितना ज़रूरी है.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
एक ऑब्जेक्ट है, जिसे ब्राउज़र ने बनाया है. इसमें वह जानकारी शामिल होती है जिसके बारे में ब्राउज़र को पता है. साथ ही, इसकी पुष्टि की जा सकती है कि विक्रेता की नीलामी स्क्रिप्ट:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
नीलामी शुरू होने से पहले, विक्रेता को उपलब्ध विज्ञापन स्लॉट के लिए
सबसे अच्छा काम का विज्ञापन मिल जाता है. scoreAd()
लॉजिक का एक हिस्सा ऐसे विज्ञापन को अस्वीकार कर देता है जो संदर्भ के हिसाब से तय किए गए विजेता को नहीं हरा सकता.
scoreAd()
scoreAd()
में ये आर्ग्युमेंट इस्तेमाल किए जाते हैं:
आर्ग्यूमेंट | भूमिका |
---|---|
adMetadata |
खरीदार की ओर से दिया गया आर्बिट्रेरी मेटाडेटा. |
auctionConfig |
नीलामी कॉन्फ़िगरेशन ऑब्जेक्ट को navigator.runAdAuction() को पास किया गया. |
bid |
बोली की संख्या वाली वैल्यू. |
trustedScoringSignals |
नीलामी के समय विक्रेता के भरोसेमंद सर्वर से हासिल किए गए मान, जो विज्ञापन के बारे में विक्रेता की राय को दिखाते हैं. |
अक्सर पूछे जाने वाले सवाल
नीलामी जीतने वाले का फ़ैसला कैसे लिया जाता है और उन्हें कौन चुनता है?
विक्रेता हर विज्ञापन का ज़रूरी स्कोर तय करने के लिए स्कोरिंग लॉजिक देता है और ब्राउज़र सबसे ज़्यादा स्कोर को विजेता विज्ञापन के रूप में चुनता है.
सेलर, scoreAd()
फ़ंक्शन में लॉजिक शामिल करता है. साथ ही, ब्राउज़र इस फ़ंक्शन को उस वर्कलेट में एक्ज़ीक्यूट करता है जिसमें इसके बाहर के कोड से सीमित कम्यूनिकेशन होता है. ब्राउज़र, विज्ञापनों को स्कोर नहीं देता है. स्कोरिंग लॉजिक को लागू करने और सबसे ज़्यादा स्कोर वाली बिड चुनने की ज़िम्मेदारी खास तौर पर ब्राउज़र की है.
Protected Audience API के सभी रेफ़रंस
एपीआई रेफ़रंस गाइड उपलब्ध हैं:
- Protected Audience API के लिए डेवलपर गाइड.
- सुरक्षित ऑडियंस इंटरेस्ट ग्रुप और बिड जनरेट करने के बारे में विज्ञापन खरीदार के लिए गाइड.
- सुरक्षित ऑडियंस के बारे में विज्ञापन सेलर गाइड विज्ञापन नीलामी.
- नीलामी के नतीजों की रिपोर्ट करने के लिए गाइड
- सुरक्षित ऑडियंस के लिए सबसे सही तरीके विज्ञापन नीलामी में लगने वाले समय
- सुरक्षित ऑडियंस से जुड़ी समस्या हल करना
Protected Audience API के बारे में जानकारी देने वाला टूल , सुविधाओं के इस्तेमाल और पाबंदियों के बारे में भी जानकारी देता है.