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

एपीआई के साथ काम करने का तरीका जानें. इसमें जांच के लिए Chrome फ़्लैग इस्तेमाल करने का तरीका भी शामिल है.

लागू किए जाने की स्थिति

डेमो आज़माएं

Topics API के दो डेमो उपलब्ध हैं, जिनकी मदद से एक उपयोगकर्ता के तौर पर Topics को आज़माया जा सकता है.

विषयों को कैटगरी तय करने वाला मॉडल आज़माने के लिए, विषयों का कोलैब भी चलाया जा सकता है.

विषयों को ऐक्सेस करने और उन्हें 'निगरानी में रखा गया' के तौर पर रिकॉर्ड करने के लिए, 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 को कॉल करने के मुकाबले ज़्यादा बेहतर साबित हो सकता है.

विषयों को 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 में जाकर, मौजूदा और पिछले युग के दौरान अपने ब्राउज़र के लिए देखे गए विषयों की जानकारी देख सकते हैं.

chrome://topics-internals पेज, जिसमें &#39;विषय की स्थिति&#39; पैनल चुना गया है.
chrome://topics-internals पेज विषय स्थिति पैनल विषय आईडी, रैंडम और वास्तविक विषय के असाइनमेंट और टेक्सॉनमी और मॉडल वर्शन दिखाता है.

यह स्क्रीनशॉट दिखाता है कि हाल ही में देखी गई साइटों में topics-demo-cats.glitch.me और cats-cats-cats-cats.glitch.me शामिल हैं. इस वजह से Topics API, मौजूदा epoch के लिए Pets और Cats को टॉप विषयों में से दो के तौर पर चुनता है. बाकी के तीन विषयों को बिना किसी क्रम के चुना गया, क्योंकि पांच विषय देने के लिए ब्राउज़िंग इतिहास (जो साइट विषयों पर निगरानी रखी जाती है) काफ़ी नहीं है.

संदर्भ के हिसाब से देखे गए डोमेन (हैश किए गए) कॉलम में, उस होस्टनेम की हैश की गई वैल्यू दी जाती है जिसके लिए विषय देखा गया था.

होस्टनेम के लिए अनुमानित विषय देखें

chrome://topics-internals में एक या उससे ज़्यादा होस्टनेम के लिए, टॉपिक क्लासिफ़ायर मॉडल से अनुमानित विषयों को भी देखा जा सकता है.

chrome://topics-internals पेज, जिसमें Classifier पैनल को चुना गया हो.
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-internals पेज को, सुविधाओं और पैरामीटर पैनल के साथ चुना गया है.
chrome://topics-internals सुविधाएं और पैरामीटर पैनल, चालू सुविधाएं, हर पीरियड के हिसाब से समय, विषयों की गिनती करने के लिए इस्तेमाल किए जाने वाले पीरियड की संख्या, टेक्सॉनमी वर्शन, और अन्य सेटिंग दिखाते हैं.

स्क्रीनशॉट में दिखाए गए पैरामीटर, उन फ़्लैग के मुताबिक होते हैं जिन्हें कमांड लाइन से 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")

अगले चरण

ज़्यादा जानें

लोगों से जुड़ें और सुझाव, शिकायत या राय शेयर करें