ईमेल लिखने की कार्रवाई की मदद से, लिखने के लिए यूज़र इंटरफ़ेस (यूआई) को बढ़ाना

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

ऐड-ऑन 'लिखें' यूज़र इंटरफ़ेस (यूआई) को ऐक्सेस करना

किसी ऐड-ऑन के 'लिखें' यूज़र इंटरफ़ेस (यूआई) को देखने के दो तरीके हैं. पहला तरीका है, नया ड्राफ़्ट लिखना शुरू करना या ऐड-ऑन पहले से खुला होने पर जवाब देना. दूसरा तरीका, ड्राफ़्ट लिखते समय ऐड-ऑन चालू करना है.

दोनों ही मामलों में ऐड-ऑन, ऐड-ऑन मेनिफ़ेस्ट में बताए गए ट्रिगर फ़ंक्शन को एक्ज़ीक्यूट करता है. 'लिखें' ट्रिगर फ़ंक्शन, उस कंपोज़ ऐक्शन के लिए 'लिखें' यूज़र इंटरफ़ेस (यूआई) बनाता है. इसके बाद, Gmail इसे उपयोगकर्ता को दिखाता है.

'लिखें' ऐड-ऑन बनाना

नीचे दिए गए सामान्य चरणों को अपनाकर, किसी ऐड-ऑन में लिखने की सुविधा जोड़ी जा सकती है:

1. ऐड-ऑन स्क्रिप्ट प्रोजेक्ट मेनिफ़ेस्ट में, gmail.composeTrigger फ़ील्ड जोड़ें. साथ ही, कंपोज़ से जुड़ी कार्रवाइयों के लिए ज़रूरी अनुमतियों को शामिल करने के लिए, मेनिफ़ेस्ट के स्कोप को अपडेट करें.
2. 'लिखें' ट्रिगर का फ़ंक्शन लागू करें, जो ट्रिगर के सक्रिय होने पर 'लिखें' यूज़र इंटरफ़ेस (यूआई) बनाता है. 'कंपोज़ ट्रिगर' फ़ंक्शन या तो कोई एक Card ऑब्जेक्ट या Card ऑब्जेक्ट की श्रेणी दिखाते हैं जिसमें 'लिखें' कार्रवाई के लिए 'लिखें' यूज़र इंटरफ़ेस (यूआई) शामिल है.
3. उपयोगकर्ता के कंपोज़ यूज़र इंटरफ़ेस (यूआई) इंटरैक्शन पर प्रतिक्रिया देने के लिए, ज़रूरी मिलते-जुलते कॉलबैक फ़ंक्शन लागू करें. ये फ़ंक्शन, कंपोज़ ऐक्शन नहीं हैं (जिससे सिर्फ़ 'लिखें' यूज़र इंटरफ़ेस (यूआई) दिखता है); इसके बजाय, ये अलग-अलग फ़ंक्शन हैं जो तय करते हैं कि कंपोज़ यूज़र इंटरफ़ेस के अलग-अलग एलिमेंट चुने जाने पर क्या होता है. उदाहरण के लिए, जिस यूज़र इंटरफ़ेस (यूआई) कार्ड में बटन होता है उसमें आम तौर पर एक कॉलबैक फ़ंक्शन होता है जो उपयोगकर्ता के उस बटन पर क्लिक करने पर लागू होता है. ड्राफ़्ट मैसेज के कॉन्टेंट को अपडेट करने वाले विजेट के लिए, कॉलबैक फ़ंक्शन से UpdateDraftActionResponse ऑब्जेक्ट दिखना चाहिए.

ट्रिगर फ़ंक्शन कंपोज़ करें

ऐड-ऑन के'लिखने के लिए यूज़र इंटरफ़ेस (यूआई)', ऐड-ऑन के मैसेज के यूज़र इंटरफ़ेस (यूआई) की तरह ही बनाया जाता है—कार्ड बनाने और उन्हें विजेट से भरने के लिए, Apps Script कार्ड सेवा का इस्तेमाल किया जाता है.

आपको वह gmail.composeTrigger.selectActions[].runFunction लागू करना होगा जिसे आपने अपने मेनिफ़ेस्ट में तय किया है. 'लिखें' ट्रिगर फ़ंक्शन में या तो कोई एक Card ऑब्जेक्ट या Card ऑब्जेक्ट का ऐरे होना चाहिए. जिसमें उस कार्रवाई के लिए यूज़र इंटरफ़ेस (यूआई) शामिल हो. ये फ़ंक्शन संदर्भ के हिसाब से ट्रिगर फ़ंक्शन से काफ़ी मिलते-जुलते हैं और इनकी तरह ही कार्ड बनाए जाने चाहिए.

चेतावनी: सुरक्षा वजहों से, ऐड-ऑन Google Workspace या तीसरे पक्ष की फ़ाइल ऐक्सेस करने की अनुमतियों में चुपचाप बदलाव नहीं कर सकते. उदाहरण के लिए, कोई ऐड-ऑन Dropbox फ़ाइल देखने वाले खातों के सेट में, ईमेल पाने वालों के ईमेल पते को बिना जोड़े नहीं जोड़ सकता. इसके बजाय, ऐड-ऑन को उपयोगकर्ताओं को यह बताना चाहिए कि अनुमति में बदलाव हो रहा है. ऐसे ऐड-ऑन जो उपयोगकर्ताओं को इस तरह के बदलावों के बारे में जानकारी नहीं देते हैं वे ऐड-ऑन समीक्षा में पास नहीं हो सकते.

ट्रिगर इवेंट ऑब्जेक्ट लिखें

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

इवेंट ऑब्जेक्ट में जानकारी को किस तरह व्यवस्थित किया जाता है, इस बारे में ज़्यादा जानने के लिए इवेंट ऑब्जेक्ट का स्ट्रक्चर देखें. इवेंट ऑब्जेक्ट में दी गई जानकारी, कुछ हद तक gmail.composeTrigger.draftAccess मेनिफ़ेस्ट फ़ील्ड की वैल्यू से कंट्रोल होती है:

• अगर gmail.composeTrigger.draftAccess मेनिफ़ेस्ट फ़ील्ड NONE है या इसमें शामिल नहीं है, तो इवेंट ऑब्जेक्ट में सिर्फ़ बहुत कम जानकारी होती है.

• अगर gmail.composeTrigger.draftAccess को METADATA पर सेट किया जाता है, तो 'लिखें' ट्रिगर फ़ंक्शन को भेजे गए इवेंट ऑब्जेक्ट में, ईमेल पाने वाले लोगों की सूचियां अपने-आप भर जाती है.

ध्यान दें: METADATA के ड्राफ़्ट ऐक्सेस का इस्तेमाल करने के लिए, ऐड-ऑन मेनिफ़ेस्ट में https://www.googleapis.com/auth/gmail.addons.current.message.metadata Gmail का स्कोप शामिल करना ज़रूरी है.

सक्रिय ड्राफ़्ट में सामग्री सम्मिलित करना

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

मौजूदा ड्राफ़्ट ईमेल को आसानी से अपडेट करने के लिए, कार्ड सेवा को इन क्लास के साथ बढ़ाया गया है:

• ContentType—एनम यह तय करता है कि बदला जा सकने वाला एचटीएमएल, नहीं बदला जा सकने वाला एचटीएमएल (जिसमें Gmail उपयोगकर्ता बदलाव नहीं कर सकते) या सामान्य टेक्स्ट वाला कॉन्टेंट जोड़ना है या नहीं.
• UpdateDraftActionResponse—यह, मौजूदा ड्राफ़्ट ईमेल को अपडेट करने वाली कार्रवाई का जवाब दिखाता है.
• UpdateDraftActionResponseBuilder— UpdateDraftActionResponse ऑब्जेक्ट के लिए बिल्डर.
• UpdateDraftBodyAction—ऐसी कार्रवाई को दिखाता है जो मौजूदा ड्राफ़्ट ईमेल के मुख्य हिस्से को अपडेट करती है.
• UpdateDraftBodyType—एनम, जो बताता है कि शरीर में क्या बदलाव होते हैं.
• UpdateDraftSubjectAction—ऐसी कार्रवाई को दिखाता है जो मौजूदा ड्राफ़्ट ईमेल के विषय फ़ील्ड को अपडेट करती है.
• UpdateDraftToRecipientsAction—ऐसी कार्रवाई दिखाता है जो मौजूदा ड्राफ़्ट ईमेल पाने वालों को अपडेट करती है.
• UpdateDraftCcRecipientsAction—ऐसी कार्रवाई जो मौजूदा ड्राफ़्ट ईमेल की कॉपी पाने वालों की जानकारी को अपडेट करती है.
• UpdateDraftBccRecipientsAction—ऐसी कार्रवाई दिखाता है जो मौजूदा ड्राफ़्ट ईमेल के गुप्त कॉपी पाने वालों की जानकारी अपडेट करती है.

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

उदाहरण 1

नीचे दिए गए कोड स्निपेट में, ‘लिखने के लिए यूज़र इंटरफ़ेस (यूआई)’ बनाने का तरीका बताया गया है. इससे विषय को अपडेट किया जा सकता है. साथ ही, मौजूदा ईमेल के ड्राफ़्ट के लिए, 'कॉपी', 'गुप्त कॉपी' फ़ील्ड में जोड़े गए ईमेल पतों के लिए, 'लिखें' यूज़र इंटरफ़ेस (यूआई) बनाने का तरीका बताया गया है.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

उदाहरण 2

नीचे दिया गया कोड स्निपेट, 'लिखें' यूज़र इंटरफ़ेस (यूआई) बनाने का तरीका बताता है, जो मौजूदा ड्राफ़्ट ईमेल में इमेज शामिल करता है.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }