browser.permissions

ब्यौरा

chrome.permissions एपीआई का इस्तेमाल करके, ऐप्लिकेशन इंस्टॉल करते समय नहीं, बल्कि उसे इस्तेमाल करते समय, ज़रूरी अनुमतियों के अलावा अन्य अनुमतियों का अनुरोध करें. इससे उपयोगकर्ताओं को यह समझने में मदद मिलती है कि अनुमतियों की ज़रूरत क्यों है और वे सिर्फ़ ज़रूरी अनुमतियां देते हैं.

कॉन्सेप्ट और इस्तेमाल

अनुमति से जुड़ी चेतावनियां, एपीआई से मिलने वाली सुविधाओं के बारे में बताती हैं. हालांकि, इनमें से कुछ चेतावनियां साफ़ तौर पर समझ नहीं आतीं. अनुमतियों से जुड़ा एपीआई, डेवलपर को अनुमति से जुड़ी चेतावनियों के बारे में बताने और धीरे-धीरे नई सुविधाएं लॉन्च करने की अनुमति देता है. इससे उपयोगकर्ताओं को एक्सटेंशन के बारे में बिना किसी जोखिम के जानकारी मिलती है. इससे उपयोगकर्ता यह तय कर सकते हैं कि उन्हें कितना ऐक्सेस देना है और कौनसी सुविधाएं चालू करनी हैं.

उदाहरण के लिए, वैकल्पिक अनुमतियों वाले एक्सटेंशन का मुख्य फ़ंक्शन, 'नया टैब' पेज को बदलना है. एक सुविधा, उपयोगकर्ता के दिन के लक्ष्य को दिखा रही है. इस सुविधा के लिए, सिर्फ़ स्टोरेज की अनुमति ज़रूरी है. इसके लिए, कोई चेतावनी नहीं दी जाती. एक्सटेंशन में एक अतिरिक्त सुविधा है. उपयोगकर्ता, इस बटन पर क्लिक करके उसे चालू कर सकते हैं:

एक्सटेंशन का बटन, जिससे अतिरिक्त सुविधाएं चालू की जा सकती हैं.
एक्सटेंशन का बटन, जिससे अतिरिक्त सुविधाएं चालू की जा सकती हैं.

उपयोगकर्ता की सबसे ज़्यादा विज़िट की गई साइटें दिखाने के लिए, topSites अनुमति की ज़रूरत होती है. इसके लिए, यह चेतावनी दी जाती है.

topSites API के लिए एक्सटेंशन की चेतावनी.
topSites एपीआई के लिए एक्सटेंशन की चेतावनी

वैकल्पिक अनुमतियां लागू करना

पहला चरण: तय करें कि कौनसी अनुमतियां ज़रूरी हैं और कौनसी वैकल्पिक हैं

कोई एक्सटेंशन, ज़रूरी और वैकल्पिक, दोनों तरह की अनुमतियों का एलान कर सकता है. आम तौर पर, आपको:

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

ज़रूरी अनुमतियों के फ़ायदे:

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

ज़रूरी नहीं अनुमतियों के फ़ायदे:

  • बेहतर सुरक्षा: एक्सटेंशन कम अनुमतियों के साथ काम करते हैं, क्योंकि उपयोगकर्ता सिर्फ़ ज़रूरी अनुमतियां चालू करते हैं.
  • उपयोगकर्ताओं को बेहतर जानकारी मिलती है: जब उपयोगकर्ता किसी सुविधा को चालू करता है, तो एक्सटेंशन यह बता सकता है कि उसे किसी खास अनुमति की ज़रूरत क्यों है.
  • आसान अपग्रेड: एक्सटेंशन को अपग्रेड करने पर, Chrome उसे आपके उपयोगकर्ताओं के लिए बंद नहीं करेगा. ऐसा तब होगा, जब अपग्रेड में ज़रूरी अनुमतियों के बजाय वैकल्पिक अनुमतियां जोड़ी जाएंगी.

दूसरा चरण: मेनिफ़ेस्ट में वैकल्पिक अनुमतियों का एलान करना

अपने एक्सटेंशन मेनिफ़ेस्ट में, optional_permissions कुंजी के साथ वैकल्पिक अनुमतियों का एलान करें. इसके लिए, अनुमतियां फ़ील्ड वाले फ़ॉर्मैट का ही इस्तेमाल करें:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

अगर आपको ऐसे होस्ट का अनुरोध करना है जो सिर्फ़ रनटाइम के दौरान मिलते हैं, तो अपने एक्सटेंशन के optional_host_permissions फ़ील्ड में "https://*/*" शामिल करें. इससे आपको "Permissions.origins" में किसी भी ऑरिजिन को तय करने की सुविधा मिलती है. हालांकि, इसके लिए ज़रूरी है कि उसकी स्कीम मैच करती हो.

ऐसी अनुमतियां जिन्हें वैकल्पिक के तौर पर तय नहीं किया जा सकता

Chrome एक्सटेंशन की ज़्यादातर अनुमतियों को 'ज़रूरी नहीं है' के तौर पर मार्क किया जा सकता है. हालांकि, इन अनुमतियों को मार्क नहीं किया जा सकता.

अनुमति ब्यौरा
"debugger" browser.debugger एपीआई, Chrome के रिमोट डीबगिंग प्रोटोकॉल के लिए, ट्रांसपोर्ट के वैकल्पिक तरीके के तौर पर काम करता है.
"declarativeNetRequest" इससे एक्सटेंशन को browser.declarativeNetRequest एपीआई का ऐक्सेस मिलता है.
"devtools" एक्सटेंशन को Chrome DevTools की सुविधाओं को बढ़ाने की अनुमति देता है.
"geolocation" एक्सटेंशन को HTML5 जियोलोकेशन एपीआई इस्तेमाल करने की अनुमति देता है.
"mdns" एक्सटेंशन को browser.mdns एपीआई को ऐक्सेस करने की अनुमति देता है.
"proxy" यह एक्सटेंशन को browser.proxy एपीआई का ऐक्सेस देता है, ताकि Chrome की प्रॉक्सी सेटिंग को मैनेज किया जा सके.
"tts" browser.tts एपीआई, लिखाई को बोली में बदलने की सुविधा (टीटीएस) का इस्तेमाल करके, टेक्स्ट को बोली में बदलता है.
"ttsEngine" browser.ttsEngine एपीआई, एक्सटेंशन का इस्तेमाल करके, लिखे गए शब्दों को सुनने की सुविधा (टीटीएस) देने वाले इंजन को लागू करता है.
"wallpaper" सिर्फ़ ChromeOS के लिए. ChromeOS का वॉलपेपर बदलने के लिए, browser.wallpaper एपीआई का इस्तेमाल करें.

उपलब्ध अनुमतियों और उनकी चेतावनियों के बारे में ज़्यादा जानकारी के लिए, अनुमतियों का एलान करें देखें.

तीसरा चरण: वैकल्पिक अनुमतियों का अनुरोध करना

permissions.request() का इस्तेमाल करके, उपयोगकर्ता के जेस्चर से अनुमतियों का अनुरोध करें:

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  browser.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

अगर अनुमतियां जोड़ने पर, उपयोगकर्ता को पहले से देखे और स्वीकार किए गए चेतावनी वाले मैसेज से अलग मैसेज दिखते हैं, तो Chrome उपयोगकर्ता को इसकी सूचना देता है. उदाहरण के लिए, पिछले कोड की वजह से इस तरह का प्रॉम्प्ट दिख सकता है:

अनुमति की पुष्टि करने वाले प्रॉम्प्ट का उदाहरण.
अनुमति की पुष्टि करने वाले प्रॉम्प्ट का उदाहरण.

चौथा चरण: एक्सटेंशन की मौजूदा अनुमतियां देखना

यह देखने के लिए कि आपके एक्सटेंशन के पास कोई खास अनुमति या अनुमतियों का सेट है या नहीं, permission.contains() का इस्तेमाल करें:

browser.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

पांचवां चरण: अनुमतियां हटाना

जब आपको अनुमतियों की ज़रूरत न हो, तो उन्हें हटा दें. अनुमति हटाए जाने के बाद, permissions.request() को कॉल करने पर, आम तौर पर उपयोगकर्ता को सूचना दिए बिना ही अनुमति वापस जोड़ दी जाती है.

browser.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

टाइप

Permissions

प्रॉपर्टी

  • origins

    string[] ज़रूरी नहीं

    होस्ट की अनुमतियों की सूची. इसमें मेनिफ़ेस्ट में optional_permissions या permissions कुंजियों में बताई गई अनुमतियां और कॉन्टेंट स्क्रिप्ट से जुड़ी अनुमतियां शामिल हैं.

  • अनुमतियां

    string[] ज़रूरी नहीं

    नाम वाली अनुमतियों की सूची (इसमें होस्ट या ऑरिजिन शामिल नहीं हैं).

तरीके

addHostAccessRequest()

Chrome 133+ browser.* Chrome 148 से MV3+ 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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

पैरामीटर

  • CANNOT TRANSLATE

    ऑब्जेक्ट

    • documentId

      string ज़रूरी नहीं

      उस दस्तावेज़ का आईडी जिसमें होस्ट ऐक्सेस के अनुरोध दिखाए जा सकते हैं. यह टैब में मौजूद टॉप-लेवल दस्तावेज़ होना चाहिए. अगर यह अनुमति दी जाती है, तो अनुरोध को दिए गए दस्तावेज़ के टैब पर दिखाया जाता है. साथ ही, दस्तावेज़ के नए ऑरिजिन पर जाने पर, इसे हटा दिया जाता है. नया अनुरोध जोड़ने पर, tabId के लिए किया गया कोई भी मौजूदा अनुरोध बदल जाएगा. यह या tabId की वैल्यू सबमिट करना ज़रूरी है.

    • पैटर्न

      string ज़रूरी नहीं

      वह यूआरएल पैटर्न जहां होस्ट ऐक्सेस के अनुरोध दिखाए जा सकते हैं. अगर होस्ट ऐक्सेस के अनुरोध दिए जाते हैं, तो वे सिर्फ़ इस पैटर्न से मैच करने वाले यूआरएल पर दिखाए जाएंगे.

    • tabId

      number ज़रूरी नहीं

      उस टैब का आईडी जहां होस्ट ऐक्सेस के अनुरोध दिखाए जा सकते हैं. अगर यह जानकारी दी जाती है, तो अनुरोध को तय किए गए टैब पर दिखाया जाता है. साथ ही, टैब के किसी नए ऑरिजिन पर जाने पर, अनुरोध को हटा दिया जाता है. नया अनुरोध जोड़ने पर, documentId के लिए किया गया मौजूदा अनुरोध बदल जाएगा. यह या documentId की वैल्यू सबमिट करना ज़रूरी है.

रिटर्न

  • वादा<शून्य>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

यह जांच करता है कि एक्सटेंशन के पास बताई गई अनुमतियां हैं या नहीं.

पैरामीटर

रिटर्न

  • Promise<boolean>

    Chrome 96+ Chrome 148 से browser.*

getAll()

browser.permissions.getAll(): Promise<Permissions>

इससे एक्सटेंशन को मिली अनुमतियों के मौजूदा सेट की जानकारी मिलती है.

रिटर्न

  • Promise<Permissions>

    Chrome 96+ Chrome 148 से browser.*

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

इससे, चुनी गई अनुमतियों का ऐक्सेस हट जाता है. अगर अनुमतियां हटाने में कोई समस्या आती है, तो प्रॉमिस को अस्वीकार कर दिया जाएगा.

पैरामीटर

रिटर्न

  • Promise<boolean>

    Chrome 96+ Chrome 148 से browser.*

removeHostAccessRequest()

Chrome 133+ browser.* Chrome 148 से MV3+ 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

अगर होस्ट के ऐक्सेस का अनुरोध मौजूद है, तो उसे हटाता है.

पैरामीटर

  • CANNOT TRANSLATE

    ऑब्जेक्ट

    • documentId

      string ज़रूरी नहीं

      उस दस्तावेज़ का आईडी जिससे होस्ट ऐक्सेस का अनुरोध हटाया जाएगा. यह टैब में मौजूद टॉप-लेवल दस्तावेज़ होना चाहिए. यह या tabId की वैल्यू सबमिट करना ज़रूरी है.

    • पैटर्न

      string ज़रूरी नहीं

      वह यूआरएल पैटर्न जहां से होस्ट ऐक्सेस का अनुरोध हटाया जाएगा. अगर यह वैल्यू दी गई है, तो यह होस्ट ऐक्सेस के किसी मौजूदा अनुरोध के पैटर्न से पूरी तरह मैच होनी चाहिए.

    • tabId

      number ज़रूरी नहीं

      उस टैब का आईडी जहां से होस्ट ऐक्सेस का अनुरोध हटाया जाएगा. यह या documentId की वैल्यू सबमिट करना ज़रूरी है.

रिटर्न

  • वादा<शून्य>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

यह तय की गई अनुमतियों के ऐक्सेस का अनुरोध करता है. साथ ही, ज़रूरत पड़ने पर उपयोगकर्ता को एक प्रॉम्प्ट दिखाता है. इन अनुमतियों को मेनिफ़ेस्ट के optional_permissions फ़ील्ड में तय किया जाना चाहिए या ये ऐसी ज़रूरी अनुमतियां होनी चाहिए जिन्हें उपयोगकर्ता ने नहीं दिया है. ऑरिजिन पैटर्न में दिए गए पाथ को अनदेखा किया जाएगा. आपके पास वैकल्पिक ऑरिजिन अनुमतियों के सबसेट का अनुरोध करने का विकल्प होता है. उदाहरण के लिए, अगर मेनिफ़ेस्ट के optional_permissions सेक्शन में *://*\/* तय किया जाता है, तो http://example.com/ का अनुरोध किया जा सकता है. अगर अनुमतियों का अनुरोध करने में कोई समस्या आती है, तो प्रॉमिस को अस्वीकार कर दिया जाएगा.

पैरामीटर

रिटर्न

  • Promise<boolean>

    Chrome 96+ Chrome 148 से browser.*

इवेंट

onAdded

browser.permissions.onAdded.addListener(
  callback: function,
)

एक्सटेंशन को नई अनुमतियां मिलने पर ट्रिगर होता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर कुछ ऐसा दिखता है: 

    (permissions: Permissions) => void

onRemoved

browser.permissions.onRemoved.addListener(
  callback: function,
)

यह तब ट्रिगर होता है, जब एक्सटेंशन से अनुमतियों का ऐक्सेस हटा दिया जाता है.

पैरामीटर

  • कॉलबैक

    फ़ंक्शन

    callback पैरामीटर कुछ ऐसा दिखता है: 

    (permissions: Permissions) => void