एडिटर ऐड-ऑन को अनुमति देना

कई Google Apps स्क्रिप्ट ऐप्लिकेशन के लिए अनुमति पाना आसान है. जब कोई व्यक्ति स्क्रिप्ट का इस्तेमाल करने की कोशिश करता है, तो स्क्रिप्ट प्रोजेक्ट, ज़रूरी अनुमतियों के बारे में पूछता है.

एडिटर ऐड-ऑन के लिए अनुमति का मॉडल कई वजहों से ज़्यादा जटिल है:

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

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

• जब कोई दस्तावेज़ खुलता है, तो एडिटर ऐड-ऑन अपने onOpen फ़ंक्शन अपने-आप चलाते हैं.

उपयोगकर्ता के डेटा को सुरक्षित रखने के लिए, अनुमति के ऐसे मोड लागू किए जाते हैं जिनकी वजह से कुछ सेवाएं onOpen के लिए उपलब्ध नहीं होतीं. इस गाइड में बताया गया है कि आपका कोड क्या कर सकता है और कब.

अनुमति का मॉडल

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

एडिटर ऐड-ऑन की स्थितियां

एक्सटेंशन मेन्यू में मौजूद एडिटर ऐड-ऑन इंस्टॉल किए गए होते हैं, चालू किए गए होते हैं या दोनों:

• किसी उपयोगकर्ता के लिए कोई ऐड-ऑन इंस्टॉल तब होता है, जब वह या उसका एडमिन, Google Workspace Marketplace से उसे हासिल करता है और अपने Google डेटा को ऐक्सेस करने की अनुमति देता है.
• किसी दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में कोई ऐड-ऑन चालू तब होता है, जब कोई व्यक्ति उसका इस्तेमाल करता है.
• जब लोग किसी फ़ाइल पर साथ मिलकर काम करते हैं और उनमें से कोई एक ऐड-ऑन का इस्तेमाल करता है, तो वह ऐड-ऑन उस उपयोगकर्ता के लिए इंस्टॉल हो जाता है और फ़ाइल के लिए चालू हो जाता है.

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

अनुमति के मोड

जब कोई उपयोगकर्ता कोई दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट खोलता है, तो एडिटर ऐड-ऑन का onOpen फ़ंक्शन अपने-आप चलता है. उपयोगकर्ताओं के डेटा को सुरक्षित रखने के लिए, Apps Script इस बात पर पाबंदी लगाता है कि onOpen फ़ंक्शन क्या कर सकता है. एडिटर ऐड-ऑन की स्थिति से यह तय होता है कि onOpen फ़ंक्शन, अनुमति के किस मोड में चलता है.

अगर किसी फ़ाइल, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट में कोई एडिटर ऐड-ऑन चालू है, तो onOpen, AuthMode.LIMITED में चलता है. अगर ऐड-ऑन चालू नहीं है और सिर्फ़ इंस्टॉल किया गया है, तो onOpen AuthMode.NONE में चलता है.

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

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

सिर्फ़ पब्लिश किए गए एडिटर ऐड-ऑन, AuthMode.NONE में हो सकते हैं. पब्लिश नहीं किए गए एडिटर ऐड-ऑन, onOpen को AuthMode.LIMITED में चलाते हैं. हालांकि, अनुमति के किसी भी मोड में ऐसा किया जा सकता है. इसके लिए, किसी एडिटर ऐड-ऑन को टेस्ट करें.

Apps Script, अनुमति के मोड को Apps Script के इवेंट पैरामीटर, e की authMode प्रॉपर्टी के तौर पर पास करता है. e.authMode की वैल्यू, Apps Script के ScriptApp.AuthMode enum में मौजूद किसी कॉन्स्टैंट से मेल खाती है.

अनुमति के मोड, Apps Script के सभी एक्ज़ीक्यूशन के तरीकों पर लागू होते हैं, इनमें स्क्रिप्ट एडिटर से, मेन्यू के किसी आइटम से या Apps Script google.script.run कॉल से स्क्रिप्ट चलाना शामिल है. हालांकि, प्रॉपर्टी की जांच सिर्फ़ तब की जा सकती है, जब स्क्रिप्ट किसी ट्रिगर की वजह से चलती है. जैसे, onOpen, onEdit या onInstall.e.authMode Google Sheets में मौजूद कस्टम फ़ंक्शन, अनुमति के अपने मोड, AuthMode.CUSTOM_FUNCTION का इस्तेमाल करते हैं. यह LIMITED जैसा ही है, लेकिन इसमें थोड़ी अलग पाबंदियां हैं. अन्य सभी मामलों में, स्क्रिप्ट AuthMode.FULL में चलती हैं. इसके बारे में, यहां दी गई टेबल में बताया गया है.

एडिटर ऐड-ऑन की अनुमति का लाइफ़साइकल

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

एडिटर ऐड-ऑन इंस्टॉल किया गया है

जब स्टोर से कोई एडिटर ऐड-ऑन इंस्टॉल किया जाता है, तो उसका onInstall फ़ंक्शन, AuthMode.FULL में चलता है. अनुमति के इस मोड में, ऐड-ऑन सेटअप की जटिल प्रोसेस चला सकता है. मेन्यू के आइटम बनाने के लिए भी onInstall का इस्तेमाल करना चाहिए, क्योंकि दस्तावेज़, फ़ॉर्म, प्रज़ेंटेशन या स्प्रेडशीट पहले से ही खुली होती है और आपका onOpen फ़ंक्शन नहीं चला होता. यहां दिए गए उदाहरण में, onInstall फ़ंक्शन से onOpen फ़ंक्शन को कॉल करने का तरीका बताया गया है:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

एडिटर ऐड-ऑन खोला गया है

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

अगर कोई ऐड-ऑन सिर्फ़ बुनियादी मेन्यू बनाता है, तो मोड से कोई फ़र्क़ नहीं पड़ता. यहां दिए गए उदाहरण में, एक बुनियादी onOpen फ़ंक्शन दिखाया गया है:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

स्टोर की गई Apps Script प्रॉपर्टी के आधार पर, डाइनैमिक मेन्यू आइटम जोड़ने, मौजूदा फ़ाइल का कॉन्टेंट पढ़ने या अन्य बेहतर टास्क करने के लिए, आपको अनुमति के मोड की पहचान करनी होगी और उसे सही तरीके से मैनेज करना होगा.

यहां दिए गए उदाहरण में, एक बेहतर onOpen फ़ंक्शन दिखाया गया है. यह अनुमति के मोड के आधार पर अपनी कार्रवाई बदलता है:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

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

AuthMode.LIMITED में, ऐड-ऑन साइडबार या डायलॉग नहीं खोल सकते. साइडबार और डायलॉग खोलने के लिए, मेन्यू आइटम का इस्तेमाल किया जा सकता है, क्योंकि ये AuthMode.FULL में चलते हैं.

कोई उपयोगकर्ता, एडिटर ऐड-ऑन चलाता है

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

ऐड-ऑन के मेन्यू रेंडर न होने की समस्या हल करना

अगर आपका कोड, अनुमति के मोड को सही तरीके से मैनेज नहीं करता है, तो हो सकता है कि आपके ऐड-ऑन का मेन्यू रेंडर न हो. उदाहरण के लिए:

• कोई ऐड-ऑन, Apps Script की ऐसी सेवा को चलाने की कोशिश करता है जिसे अनुमति के मौजूदा मोड में इस्तेमाल नहीं किया जा सकता.

• कोई ऐड-ऑन, उपयोगकर्ता के साथ इंटरैक्ट करने से पहले, सेवा कॉल चलाने की कोशिश करता है.

AuthMode.NONE में, अनुमति से जुड़ी गड़बड़ियां पैदा करने वाली सेवा कॉल को हटाने या उसकी जगह बदलने के लिए, ये कार्रवाइयां करें:

1. अपने ऐड-ऑन के लिए Apps Script प्रोजेक्ट खोलें और onOpen फ़ंक्शन ढूंढें.
2. onOpen फ़ंक्शन में, Apps Script की सेवाओं या उनसे जुड़े ऑब्जेक्ट के बारे में खोजें. जैसे, PropertiesService, SpreadsheetApp या GmailApp.
3. अगर किसी सेवा का इस्तेमाल, यूज़र इंटरफ़ेस (यूआई) के एलिमेंट बनाने के अलावा किसी और काम के लिए किया जाता है, तो उसे हटाएं या उसे टिप्पणी वाले ब्लॉक में रैप करें. सिर्फ़ इन तरीकों को छोड़ें: .getUi, .createMenu, .addItem, और .addToUi. साथ ही, किसी ऐसे सेवा को ढूंढें और हटाएं जो किसी फ़ंक्शन के बाहर हो.
4. ऐसे फ़ंक्शन की पहचान करें जिनमें पिछले चरण में टिप्पणी की गई या हटाई गई कोड की लाइनें हो सकती हैं. खास तौर पर, वे फ़ंक्शन जो उनसे मिलने वाली जानकारी का इस्तेमाल करते हैं. इसके बाद, सेवा कॉल को उन फ़ंक्शन में ले जाएं जिन्हें उनकी ज़रूरत है. पिछले चरणों में किए गए बदलावों के हिसाब से, अपने कोडबेस को फिर से व्यवस्थित करें या फिर से लिखें.
5. कोड सेव करें और टेस्ट के लिए डिप्लॉयमेंट बनाएं. टेस्ट के लिए डिप्लॉयमेंट बनाते समय, पक्का करें कि कॉन्फ़िगरेशन फ़ील्ड मौजूदा उपयोगकर्ता के लिए इंस्टॉल किया गया हो और कॉन्फ़िगरेशन बॉक्स के नीचे मौजूद टेक्स्ट टेस्ट इन AuthMode.NONE हो.
6. टेस्ट के लिए डिप्लॉयमेंट लॉन्च करें और एक्सटेंशन मेन्यू खोलें.
7. अगर मेन्यू के सभी आइटम दिखते हैं, तो समस्या ठीक हो गई है. अगर आपको सिर्फ़ सहायता मेन्यू दिखता है, तो पहले चरण पर वापस जाएं. ऐसा हो सकता है कि आपने किसी सेवा कॉल को छोड़ दिया हो.

मिलते-जुलते विषय

• वेब ऐप्लिकेशन
• ऐड-ऑन के टाइप
• किसी एडिटर ऐड-ऑन को टेस्ट करना