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

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

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

डेमो आज़माएं

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

Topics colab इस्तेमाल करके, Topics का क्लासिफ़ायर मॉडल भी आज़माया जा सकता है.

विषयों को ऐक्सेस करने और उन्हें निगरानी के तौर पर रिकॉर्ड करने के लिए, JavaScript API का इस्तेमाल करें

Topics JavaScript API का एक तरीका है: document.browsingTopics(). इसके दो मकसद हैं:

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

यह तरीका ऐसा प्रॉमिस देता है जो ज़्यादा से ज़्यादा तीन विषयों के कलेक्शन के साथ मिलता है. इसमें, तीन सबसे हाल के epoch में से हर एक के लिए, किसी भी क्रम में प्रॉमिस का जवाब दिया जाता है. Epoch का मतलब है कि एक समयावधि तय होती है. Chrome को लागू करते समय, इसे एक हफ़्ते पर सेट किया जाता है.

document.browsingTopics() से मिले कलेक्शन में मौजूद हर विषय ऑब्जेक्ट में ये प्रॉपर्टी होती हैं:

  • configVersion: इस स्ट्रिंग से विषय के मौजूदा एपीआई कॉन्फ़िगरेशन की पहचान होती है, जैसे कि chrome.2
  • modelVersion: साइट के विषयों का अनुमान लगाने के लिए इस्तेमाल किए गए मशीन लर्निंग क्लासिफ़ायर की पहचान करने वाली स्ट्रिंग, उदाहरण के लिए 4
  • taxonomyVersion: ब्राउज़र में इस्तेमाल किए गए विषयों के सेट की पहचान करने वाली स्ट्रिंग, जैसे कि 2
  • topic: टेक्सॉनमी में मौजूद विषय की पहचान करने वाली संख्या, जैसे कि 309
  • version: configVersion, taxonomyVersion, और modelVersion को जोड़ने वाली स्ट्रिंग, जैसे कि chrome.2:2:4

हम नेटवर्क से मिलने वाले सुझाव को शामिल करते हैं और एपीआई पर इसे दोहराते रहते हैं. इसलिए, इस गाइड में बताए गए पैरामीटर और एपीआई की जानकारी में बदलाव किया जा सकता है. जैसे, टेक्सॉनमी का साइज़, हर हफ़्ते कैलकुलेट किए गए विषयों की संख्या, और हर कॉल पर वापस आने वाले विषयों की संख्या.

document.browsingTopics के लिए सहायता का पता लगाएं

API का इस्तेमाल करने से पहले, देखें कि यह ब्राउज़र पर काम करता है या नहीं और दस्तावेज़ में उपलब्ध है या नहीं:

'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} का मतलब है कि मेथड कॉल से मौजूदा पेज को विषयों के कैलकुलेशन में शामिल नहीं किया जाएगा.

विषयों को ऐक्सेस करने के लिए, हेडर इस्तेमाल करें और उन्हें 'निगरानी में रखा गया' के तौर पर मार्क करें

request और response हेडर के साथ.

हेडर तरीके को इस्तेमाल करने का तरीका, 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 है.

हेडर के बारे में कुछ और जानकारी:

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

अपना एपीआई लागू करने का तरीका डीबग करें

Topics API को चालू करने के बाद, chrome://topics-internals पेज डेस्कटॉप पर Chrome में उपलब्ध हो जाता है. इससे मौजूदा उपयोगकर्ता के विषय, होस्टनेम के लिए अनुमान लगाए गए विषय, और एपीआई लागू करने के बारे में तकनीकी जानकारी दिखती है. डेवलपर से मिले सुझाव, शिकायत या राय के आधार पर, हम पेज के डिज़ाइन को बेहतर बना रहे हैं और उसमें सुधार कर रहे हैं. इसके लिए, bugs.chromium.org पर जाकर अपना सुझाव दें.

अपने ब्राउज़र के लिए कैलकुलेट किए गए विषय देखें

उपयोगकर्ता chrome://topics-internals में जाकर, मौजूदा और पिछले एपिसोड के दौरान, अपने ब्राउज़र पर देखे गए विषयों के बारे में जानकारी देख सकते हैं.

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

Topics API को मौजूदा समय में लागू करने के बाद, उसमें सिर्फ़ होस्टनेम से जुड़े विषयों का अनुमान लगाया जाता है; नहीं किया जा सकता.

chrome://topics-internals क्लासिफ़ायर से अनुमानित विषय देखने के लिए, सिर्फ़ होस्टनेम (प्रोटोकॉल या पाथ के बिना) का इस्तेमाल करें. "/" को शामिल करने की कोशिश करने पर, chrome://topics-internals गड़बड़ी दिखाएगा होस्ट फ़ील्ड में.

Topics API की जानकारी देखें

Topics API को लागू करने और सेटिंग के बारे में जानकारी, chrome://topics-internals में मिल सकती है. जैसे, टेक्सॉनमी वर्शन और Epoch की अवधि. ये वैल्यू, एपीआई के लिए डिफ़ॉल्ट सेटिंग या कमांड लाइन से सेट किए गए पैरामीटर को दिखाती हैं. इससे यह पुष्टि करने में मदद मिल सकती है कि कमांड लाइन फ़्लैग ने उम्मीद के मुताबिक काम किया है.

उदाहरण में, time_period_per_epoch को 15 सेकंड पर सेट किया गया है (डिफ़ॉल्ट सेटिंग सात दिन है).

chrome://topics-internals पेज, जिसमें सुविधाएं और पैरामीटर चुने गए हैं.
chrome://topics-internals सुविधाएं और पैरामीटर पैनल, चालू की गई सुविधाएं, हर epoch का समय, विषयों की गिनती करने के लिए इस्तेमाल किए जाने वाले epoch की संख्या, टेक्सॉनमी वर्शन, और अन्य सेटिंग दिखाता है.

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

PrivacySandboxSettings4
डिफ़ॉल्ट वैल्यू: बंद
यह नीति, प्राइवसी सैंडबॉक्स की यूज़र इंटरफ़ेस (यूआई) सेटिंग की चौथी रिलीज़ को चालू करती है.

OverridePrivacySandboxSettingsLocalTesting
डिफ़ॉल्ट वैल्यू: चालू की गई
अगर यह सेटिंग चालू है, तो ब्राउज़र को इनके लिए चालू करने की ज़रूरत नहीं होगी प्राइवसी सैंडबॉक्स की सुविधाओं को चालू करना.

BrowsingTopicsBypassIPIsPubliclyRoutableCheck
डिफ़ॉल्ट वैल्यू: बंद
चालू होने पर, यह जांच की जाएगी कि आईपी पते को सार्वजनिक तौर पर रूट किया जा सकता है या नहीं इसे विषयों में शामिल किए जाने वाले किसी पेज की योग्यता तय करते समय इसे बायपास किया जाता है गणना.

BrowsingTopics:number_of_epochs_to_expose
डिफ़ॉल्ट वैल्यू: 3
किसी अनुरोध पर दिए जाने वाले विषयों की गिनती कहां से करनी है, इसकी संख्या संदर्भ. ब्राउज़र अंदरूनी तौर पर, N+1 ऐप्स तक सेव रखेगा.

BrowsingTopics:time_period_per_epoch
डिफ़ॉल्ट वैल्यू: 7d-0h-0m-0s
हर epoch का कुल समय. डीबग करने के लिए, इसे डिफ़ॉल्ट सात दिनों के बजाय 15 सेकंड पर सेट करने से मदद मिल सकती है.

BrowsingTopics:number_of_top_topics_per_epoch
डिफ़ॉल्ट वैल्यू: 5
हर epoch के हिसाब से विषयों की संख्या.

BrowsingTopics:use_random_topic_probability_percent
डिफ़ॉल्ट वैल्यू: 5
इस बात की संभावना कि किसी epoch में मौजूद किसी विषय के नतीजे, किसी भी क्रम में मिले हैं पूरी टेक्सॉनमी के विषय शामिल हैं. रैंडमनेस epoch और साइट का स्टिकी है.

BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
डिफ़ॉल्ट वैल्यू: 3
एपीआई के इस्तेमाल से जुड़े डेटा (जैसे, विषयों की निगरानी) के कितने epoch का इस्तेमाल किया जाएगा कॉल के कॉन्टेक्स्ट के लिए विषयों को फ़िल्टर किया जा सकता है.

BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
डिफ़ॉल्ट वैल्यू: 1000
हर टॉप विषय के लिए, कॉन्टेक्स्ट के हिसाब से मॉनिटर किए गए डोमेन की ज़्यादा से ज़्यादा संख्या. मकसद इस्तेमाल की जा सकने वाली मेमोरी की सीमा तय करना.

BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
डिफ़ॉल्ट वैल्यू: 100000
हर क्वेरी के लिए डेटाबेस से मिल सकने वाली एंट्री की ज़्यादा से ज़्यादा संख्या एपीआई के इस्तेमाल से जुड़े कॉन्टेक्स्ट के लिए. विषयों की गिनती करते समय, क्वेरी हर 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=() Permissions-Policy हेडर जोड़ें, ताकि उस पेज पर मौजूद सभी उपयोगकर्ताओं को विषयों का हिसाब लगाने से रोका जा सके. इसके बाद, आपकी साइट के अन्य पेजों पर जाने पर इसका कोई असर नहीं पड़ेगा: अगर आपने किसी पेज पर Topics API को ब्लॉक करने के लिए कोई नीति सेट की है, तो इसका असर दूसरे पेजों पर नहीं पड़ेगा.

आपके पास यह कंट्रोल करने का विकल्प भी है कि तीसरे पक्ष के किन ऐप्लिकेशन या कंपनियों के पास आपके पेज पर मौजूद विषयों का ऐक्सेस हो. इसके लिए, Permissions-Policy हेडर का इस्तेमाल करें और तीसरे पक्ष को Topics API का ऐक्सेस कंट्रोल करें. हेडर के पैरामीटर के तौर पर, self और उन डोमेन का इस्तेमाल करें जिन्हें आपको एपीआई का ऐक्सेस देना है. उदाहरण के लिए, अपने ऑरिजिन और https://example.com को छोड़कर, अन्य सभी ब्राउज़िंग कॉन्टेक्स्ट में Topics API के इस्तेमाल को पूरी तरह से बंद करने के लिए, यहां दिया गया एचटीटीपी रिस्पॉन्स हेडर सेट करें:

Permissions-Policy: browsing-topics=(self "https://example.com")

अगले चरण

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

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