एपीआई के साथ काम करने का तरीका जानें. इसमें जांच के लिए Chrome फ़्लैग इस्तेमाल करने का तरीका भी शामिल है.
लागू किए जाने की स्थिति
- Topics API ने सार्वजनिक बातचीत के चरण को पूरा कर लिया है और फ़िलहाल यह 99 प्रतिशत उपयोगकर्ताओं के लिए उपलब्ध है. इसे अब 100 प्रतिशत तक इस्तेमाल किया जा सकता है.
- Topics API पर सुझाव या राय देने के लिए, विषय की जानकारी देने वाले पेज पर समस्या बनाएं या वेब विज्ञापन कारोबार की जगहों के ग्रुप को बेहतर बनाने से जुड़ी चर्चा में हिस्सा लें. जानकारी देने वाले टूल में कई ऐसे सवाल हैं जिनका जवाब देना अभी बाकी है.
- प्राइवसी सैंडबॉक्स की टाइमलाइन, Topics API और प्राइवसी सैंडबॉक्स के अन्य प्रपोज़ल को लागू करने की टाइमलाइन से जुड़ी जानकारी देती है.
- Topics API: नए अपडेट में, Topics API और उसे लागू करने के तरीके में हुए बदलावों और सुधारों की जानकारी दी गई है.
डेमो लें
Topics API के दो डेमो उपलब्ध हैं, जिनकी मदद से एक उपयोगकर्ता के तौर पर Topics को आज़माया जा सकता है.
- JavaScript एपीआई का डेमो: topics-demo.glitch.me.
- हेडर डेमो: topics-fetch-demo.glitch.me
विषयों को कैटगरी तय करने वाला मॉडल आज़माने के लिए, विषयों का कोलैब भी चलाया जा सकता है.
विषयों को ऐक्सेस करने और उन्हें 'निगरानी में रखा गया' के तौर पर रिकॉर्ड करने के लिए, JavaScript API का इस्तेमाल करें
Topics JavaScript API का एक तरीका है: document.browsingTopics()
. इसके दो मकसद हैं:
- ब्राउज़र को बताएं कि मौजूदा पेज विज़िट को कॉलर के लिए देखा गया है, ताकि बाद में इसका इस्तेमाल उपयोगकर्ता (कॉलर के लिए) के विषयों का हिसाब लगाने के लिए किया जा सके.
- उपयोगकर्ता के उन विषयों को ऐक्सेस करें जिन्हें कॉलर ने देखा है.
इस तरीके से, ऐसा प्रॉमिस मिलता है जिसमें ज़्यादा से ज़्यादा तीन विषय शामिल होते हैं. यह सबसे हाल के तीन epoch में से हर एक के लिए होता है. यह क्रम बिना किसी क्रम के होता है. epoch एक समयावधि होती है, जिसे Chrome लागू करने के दौरान एक हफ़्ते पर सेट किया जाता है.
document.browsingTopics()
से मिलने वाले कलेक्शन में हर विषय से जुड़े ऑब्जेक्ट में ये प्रॉपर्टी होती हैं:
configVersion
: Topics API के मौजूदा कॉन्फ़िगरेशन की पहचान करने वाली स्ट्रिंग, जैसे किchrome.2
modelVersion
: कैटगरी तय करने वाले मशीन-लर्निंग टूल की पहचान करने वाली स्ट्रिंग, जिसका इस्तेमाल साइट के विषय का अनुमान लगाने के लिए किया जाता है. उदाहरण के लिए,4
taxonomyVersion
: ब्राउज़र में इस्तेमाल किए गए विषयों के सेट की पहचान करने वाली स्ट्रिंग, उदाहरण के लिए,2
topic
: कैटगरी में बताए गए विषय की पहचान करने वाली संख्या, उदाहरण के लिए309
version
:configVersion
,taxonomyVersion
, औरmodelVersion
को जोड़ने वाली स्ट्रिंग, उदाहरण के लिए,chrome.2:2:4
नेटवर्क से जुड़े सुझाव, शिकायत या राय को लागू करने और एपीआई पर कार्रवाई करने की वजह से, इस गाइड में दिए गए पैरामीटर और एपीआई की जानकारी (जैसे, अलग-अलग कैटगरी का साइज़, हर हफ़्ते गिने गए विषयों की संख्या, और हर कॉल में लौटाए गए विषयों की संख्या) में बदलाव हो सकता है.
दस्तावेज़.browsingTopics के लिए सहायता का पता लगाने के लिए
एपीआई का इस्तेमाल करने से पहले, देख लें कि वह ब्राउज़र पर काम करता है या नहीं और दस्तावेज़ में उपलब्ध है या नहीं:
'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() is not supported on this page');
JavaScript API की मदद से विषयों को ऐक्सेस करें
यहां पर उदाहरण के तौर पर बताया गया है कि मौजूदा उपयोगकर्ता के लिए विषयों को ऐक्सेस करने के लिए, एपीआई का कितना इस्तेमाल किया जा सकता है.
try {
// Get the array of top topics for this user.
const topics = await document.browsingTopics();
// Request an ad creative, providing topics information.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})
// Get the JSON from the response.
const creative = await response.json();
// Display ad.
} catch (error) {
// Handle error.
}
स्थिति में बदलाव किए बिना विषयों को ऐक्सेस करें
document.browsingTopics()
उन विषयों को दिखाता है जिन्हें कॉलर ने मौजूदा उपयोगकर्ता के लिए देखा है. डिफ़ॉल्ट रूप से, इस तरीके की मदद से ब्राउज़र, मौजूदा पेज पर हुई विज़िट को भी कॉलर के हिसाब से रिकॉर्ड करता है, ताकि बाद में इसका इस्तेमाल विषयों का हिसाब लगाने में किया जा सके. Chrome 108 से, इस तरीके को एक वैकल्पिक तर्क पास किया जा सकता है, ताकि पेज विज़िट को रिकॉर्ड होने से रोका जा सके: {skipObservation:true}
.
दूसरे शब्दों में, {skipObservation:true}
का मतलब है कि तरीके को कॉल करने से मौजूदा पेज को विषयों की गिनती में शामिल नहीं किया जाएगा.
विषयों को ऐक्सेस करने और उन्हें 'देखा गया' के तौर पर मार्क करने के लिए, हेडर का इस्तेमाल करें
विषयों को ऐक्सेस किया जा सकता है. साथ ही, अनुरोध और रिस्पॉन्स हेडर की मदद से, पेज विज़िट को 'देखा गया' के तौर पर मार्क किया जा सकता है.
JavaScript API के मुकाबले हेडर वाले तरीके का इस्तेमाल करन�� ज़्यादा बेहतर साबित हो सकता है. ऐसा इसलिए, क्योंकि एपीआई को क्रॉस-ऑरिजिन iframe बनाना और उससे document.browsingTopics()
कॉल करना ज़रूरी होता है. कॉल के लिए क्रॉस-ऑरिजिन iframe का इस्तेमाल करना चाहिए, क्योंकि एपीआई को शुरू करने के कॉन्टेक्स्ट का इस्तेमाल यह पक्का करने के लिए किया जाता है कि ब्राउज़र, कॉलर को सही विषय दे. विषयों के बारे में जानकारी देने वाले टूल में आगे चर्चा की गई है: क्या फे़च का इस्तेमाल करके, अनुरोध के हेडर के तौर पर विषय भेजने का कोई तरीका होना चाहिए? .
विषयों को fetch()
या XHR
अनुरोध के Sec-Browsing-Topics
हेडर से ऐक्सेस किया जा सकता है.
अनुरोध के रिस्पॉन्स में Observe-Browsing-Topics: ?1
हेडर सेट करने से, ब्राउज़र मौजूदा पेज विज़िट को कॉलर के हिसाब से रिकॉर्ड करता है, ताकि बाद में इसका इस्तेमाल विषयों की गिनती में किया जा सके.
एचटीटीपी हेडर की मदद से विषयों को दो तरीकों से ऐक्सेस किया जा सकता है और उनकी निगरानी की जा सकती है:
fetch()
:fetch()
अनुरोध के विकल्प पैरामीटर में{browsingTopics: true}
जोड़ें. विषय के हेडर का डेमो में, इसका आसान उदाहरण दिया गया है.- iframe एट्रिब्यूट:
browsingtopics
एट्रिब्यूट को किसी<iframe>
एलिमेंट में जोड़ें या उसके बराबर की JavaScript प्रॉपर्टीiframe.browsingTopics = true
सेट करें. iframe सोर्स का रजिस्टर किया जा सकने वाला डोमेन, कॉलर का डोमेन है: उदाहरण के लिए,<iframe src="https://example.com" browsingtopics></iframe>
के लिए: कॉल करने वाला,example.com
है.
��ेडर के बारे में कुछ अतिरिक्त जानकारी:
- रीडायरेक्ट को फ़ॉलो किया जाएगा और रीडायरेक्ट अनुरोध में भेजे गए विषय, रीडायरेक्ट यूआरएल के लिए खास होंगे.
- अनुरोध के हेडर में कॉलर की स्थिति में तब तक बदलाव नहीं होगा, जब तक संबंधित रिस्पॉन्स हेडर मौजूद न हो. इसका मतलब है कि रिस्पॉन्स हेडर के बिना, पेज पर आने वाली विज़िट को 'निगरानी' के तौर पर रिकॉर्ड नहीं किया जाएगा. इसलिए, उपयोगकर्ता के टॉपिक कैलकुलेशन पर इसका कोई असर नहीं पड़ेगा.
- रिस्पॉन्स हेडर पर सिर्फ़ तब काम किया जाता है, जब संबंधित अनुरोध में विषय का हेडर शामिल हो.
- अनुरोध का यूआरएल, रजिस्टर किया जा सकने वाला वह डोमेन देता है जिसे कॉलर डोमेन के तौर पर रिकॉर्ड किया जाता है.
एपीआई लागू करने की प्रक्रिया को डीबग करना
Topics API चालू करने के बाद, डेस्कटॉप पर Chrome में chrome://topics-internals
पेज उपलब्ध होगा. इसमें मौजूदा उपयोगकर्ता के लिए विषय, होस्टनेम के लिए अनुमानित विषय, और एपीआई लागू करने के बारे में तकनीकी जानकारी दिखती है. डेवलपर से मिले सुझाव, राय या शिकायत के आधार पर, हम पेज के डिज़ाइन को दोहरा रहे हैं और उसे बेहतर बना रहे हैं. इसके लिए, bugs.chromium.org पर जाएं. इसके बाद, अपने सुझाव, शिकायत या राय भेजें.
ब्राउज़र के हिसाब से तय किए गए विषय देखें
उपयोगकर्ता, chrome://topics-internals
में जाकर, मौजूदा और पिछले युग के दौरान अपने ब्राउज़र के लिए देखे गए विषयों की जानकारी देख सकते हैं.
��ह स्क्रीनशॉट दिखाता है कि हाल ही में देखी गई साइटों में topics-demo-cats.glitch.me
और cats-cats-cats-cats.glitch.me
शामिल हैं. इस वजह से Topics API, मौजूदा epoch के लिए Pets
और Cats
को टॉप विषयों में से दो के तौर पर चुनता है. बाकी के तीन विषयों को बिना किसी क्रम के चुना गया, क्योंकि पांच विषय देने के लिए ब्राउज़िंग इतिहास (जो साइट विषयों पर निगरानी रखी जाती है) काफ़ी नहीं है.
संदर्भ के हिसाब से देखे गए डोमेन (हैश किए गए) कॉलम में, उस होस्टनेम की हैश की गई वैल्यू दी जाती है जिसके लिए विषय देखा गया था.
होस्टनेम के लिए अनुमानित विषय देखें
chrome://topics-internals
में एक या उससे ज़्यादा होस्टनेम के लिए, टॉपिक क्लासिफ़ायर मॉडल से अनुमानित विषयों को भी देखा जा सकता है.
फ़िलहाल, Topics API में सिर्फ़ होस्टनेम के विषय शामिल किए गए हैं. यूआरएल के किसी दूसरे हिस्से से ऐसा नहीं किया जा सकता.
chrome://topics-internals
क्लासिफ़ायर की मदद से अनुमानित विषयों को देखने के लिए, सिर्फ़ होस्टनेम का इस्तेमाल करें (प्रोटोकॉल या पाथ के बिना). अगर होस्ट फ़ील्ड में "/" को शामिल करने की कोशिश की जाती है, तो chrome://topics-internals
गड़बड़ी दिखाएगा.
Topics API की जानकारी देखें
chrome://topics-internals
में, Topics API को लागू करने और सेटिंग के बारे में जानकारी देखी जा सकती है. जैसे, कैटगरी से जुड़े वर्शन और epoch की अवधि. ये वैल्यू, एपीआई के लिए डिफ़ॉल्ट सेटिंग या कमांड लाइन से सेट किए गए पैरामीटर के बारे में बताती हैं. इससे यह पुष्टि करने में मदद मिल सकती है कि कमांड लाइन फ़्लैग ने उम्मीद के मुताबिक काम किया.
उदाहरण में, time_period_per_epoch
को 15 सेकंड पर सेट किया गया है (डिफ़ॉल्ट समय सात दिन है).
स्क्रीनशॉट में दिखाए गए पैरामीटर, उन फ़्लैग के मुताबिक होते हैं जिन्हें कमांड लाइन से Chrome चलाते समय सेट किया जा सकता है. उदाहरण के लिए, topics-fetch-demo.glitch.me पर मौजूद डेमो, इन फ़्लैग का इस्तेमाल करने का सुझाव देता है:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
नीचे दी गई सूची में, हर पैरामीटर, उसकी डिफ़ॉल्ट वैल्यू, और उसके मकसद के बारे में बताया गया है.
Chrome के फ़्लैग
BrowsingTopics
- डिफ़ॉल्ट वैल्यू: चालू है
- Topics API चालू है या नहीं.
PrivacySandboxAdsAPIsOverride
- डिफ़ॉल्ट वैल्यू: चालू है
- Ads API चालू करता है: एट्रिब्यूशन रिपोर्टिंग, सुरक्षित ऑडियंस, विषय, फ़ेंस किए गए फ़्रेम.
PrivacySandboxSettings4
- डिफ़ॉल्ट वैल्यू: बंद है
- यह प्राइवसी सैंडबॉक्स के यूज़र इंटरफ़ेस (यूआई) सेटिंग की चौथी रिलीज़ को चालू करता है.
OverridePrivacySandboxSettingsLocalTesting
- डिफ़ॉल्ट वैल्यू: चालू है
- अगर इसे चालू किया जाता है, तो ब्राउज़र को प्राइवसी सैंडबॉक्स की सुविधाओं को चालू करने के लिए, पहले से मौजूद सेटिंग को चालू करने की ज़रूरत नहीं रहेगी.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- डिफ़ॉल्ट वैल्यू: बंद है
- अगर इसे चालू किया जाता है, तो विषयों की कैलकुलेशन में किसी पेज को शामिल किया जा सकता है या नहीं, यह तय करते समय यह जांच नहीं की जाएगी कि आईपी पता सार्वजनिक तौर पर रूट किया जा सकता है या नहीं.
BrowsingTopics:number_of_epochs_to_expose
- डिफ़ॉल्ट वैल्यू: 3
- उन epoch की संख्या जहां से अनुरोध करने वाले कॉन्टेक्स्ट के लिए विषयों की गिनती करनी है. ब्राउज़र अंदरूनी तौर पर, N+1 epoch को बनाए रखेगा.
BrowsingTopics:time_period_per_epoch
- डिफ़ॉल्ट वैल्यू: 7d-0h-0m-0s
- हर epoch की अवधि. डीबग करने के लिए, डिफ़ॉल्ट तौर पर इसे सात दिनों के बजाय 15 सेकंड पर सेट करें.
BrowsingTopics:number_of_top_topics_per_epoch
- डिफ़ॉल्ट वैल्यू: 5
- हर एपिसोड के हिसाब से तय किए गए विषयों की संख्या.
BrowsingTopics:use_random_topic_probability_percent
- डिफ़ॉल्ट वैल्यू: 5
- इस बात की संभावना है कि किसी epoch का कोई विषय, विषयों की पूरी कैटगरी से बिना किसी क्रम के दिखाया जाए. रैंडमनेस, epoch और साइट के हिसाब से चिपक जाती है.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- डिफ़ॉल्ट वैल्यू: 3
- कॉलिंग कॉन्टेक्स्ट के हिसाब से विषयों को फ़िल्टर करने के लिए, एपीआई के इस्तेमाल से जुड़े डेटा (जैसे, विषयों की निगरानी) के कितने एपिसोड का इस्तेमाल किया जाएगा.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- डिफ़ॉल्ट वैल्यू: 1,000
- हर टॉप टॉपिक के लिए, कॉन्टेक्स्ट के हिसाब से मॉनिटर किए जाने वाले डोमेन की ज़्यादा से ज़्यादा संख्या. इसका मकसद इस्तेमाल की जा रही मेमोरी को सीमित करना है.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- डिफ़ॉल्ट वैल्यू: 1,00,000
- एपीआई के इस्तेमाल के कॉन्टेक्स्ट के लिए, हर क्वेरी के लिए डेटाबेस से ज़्यादा से ज़्यादा एंट्री को वापस लाने की अनुमति दी जा सकती है. विषयों की गिनती के समय, क्वेरी हर epoch के लिए एक बार जनरेट होगी. इसका मकसद, ज़्यादा मेमोरी के इस्तेमाल की सीमा तय करना है.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- डिफ़ॉल्ट वैल्यू: 30
- हर पेज लोड के हिसाब से सेव किए जा सकने वाले, एपीआई के इस्तेमाल के कॉन्टेक्स्ट वाले डोमेन की ज़्यादा से ज़्यादा संख्या.
BrowsingTopics:config_version
- डिफ़ॉल्ट वैल्यू: 1
- Topics API कॉन्फ़िगरेशन पैरामीटर को कोड में बदलता है. हर वर्शन नंबर सिर्फ़ एक कॉन्फ़िगरेशन सेट के साथ मैप किया ��ाना चाहिए.
config_version
को अपडेट किए बिना कॉन्फ़िगरेशन पैरामीटर को अपडेट करना, आम तौर पर लोकल टेस्टिंग के लिए सही होता है. हालांकि, कुछ स्थितियों में ब्राउज़र में गड़बड़ी हो सकती है. इस वजह से, ब्राउज़र क्रैश हो सकता है, जैसे किnumber_of_top_topics_per_epoch
को अपडेट करना. BrowsingTopics:taxonomy_version
- डिफ़ॉल्ट वैल्यू: 1
- कैटगरी का वह वर्शन जिसे एपीआई इस्तेमाल करता है.
अपनी साइट से ऑप्ट आउट करें
अपनी साइट के कुछ पेजों के लिए, विषय की गणना करने की सुविधा से ऑप्ट आउट किया जा सकता है. इसके लिए, किसी पेज पर Permissions-Policy: browsing-topics=()
अनुमतियों से जुड़ी नीति हेडर को शामिल करें. इससे, सिर्फ़ उस पेज के सभी उपयोगकर्ताओं के लिए विषयों की गिनती को रोका जा सकता है. ऐसा होने पर, आपकी साइट के अन्य पेजों पर जाने पर कोई असर नहीं पड़ेगा: अगर आपने किसी पेज पर Topics API को ब्लॉक करने की नीति सेट की है, तो इसका असर दूसरे पेजों पर नहीं पड़ेगा.
Topics API के तीसरे पक्ष के ऐक्सेस को कंट्रोल करने के लिए, Permissions-Policy
हेडर का इस्तेमाल करके यह भी कंट्रोल किया जा सकता है कि आपके पेज पर किन तीसरे पक्षों के पास विषयों का ऐक्सेस हो. हेडर के पैरामीटर के तौर पर, self
और उन सभी डोमेन का इस्तेमाल करें जिन्हें आपको एपीआई ऐक्सेस करने की अनुमति देनी है. उदाहरण के लिए, अगर आपको अपने ऑरिजिन और https://example.com
को छोड़कर, अन्य सभी ब्राउज़िंग कॉन्टेक्स्ट में Topics API के इस्तेमाल को पूरी तरह से बंद करना है, तो यह एचटीटीपी रिस्पॉन्स हेडर सेट करें:
Permissions-Policy: browsing-topics=(self "https://example.com")
अगले चरण
- विषय और उनके काम करने के तरीके के बारे में ज़्यादा जानें.
- डेमो आज़माएं.
ज़्यादा जानें
लोगों से जुड़ें और सुझाव, शिकायत या राय शेयर करें
- GitHub: Topics API का एक्सप्लेनर पढ़ें. साथ ही, सवाल इकट्ठा करें और एपीआई के डेटा स्टोर करने से जुड़ी समस्याओं पर चर्चा को फ़ॉलो करें.
- W3C: वेब विज्ञापन कारोबार की जगहों के ग्रुप को बेहतर बनाना में, इंडस्ट्री के इस्तेमाल के उदाहरणों पर चर्चा करें.
- एलान: ईमेल पाने वाले लोगों की सूची में शामिल हों या उसे देखें.
- प्राइवसी सैंडबॉक्स डेवलपर सहायता: प्राइवसी सैंडबॉक्स डेवलपर सहायता रेपो पर सवाल पूछें और होने वाली चर्चाओं में शामिल हों.
- Chromium: Chrome में जांच के लिए अभी उपलब्ध लागू किए जाने के बारे में सवाल पूछने के लिए, Chromium बग की फ़ाइल करें.