मैसेज यूज़र इंटरफ़ेस (यूआई) को बढ़ाना

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

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

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

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

मैसेज ऐड-ऑन बनाना

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

  1. ऐड-ऑन स्क्रिप्ट प्रोजेक्ट के मेनिफ़ेस्ट में सही फ़ील्ड जोड़ें. इनमें मैसेज फ़ंक्शन के लिए ज़रूरी स्कोप भी शामिल हैं. मेनिफ़ेस्ट में सशर्त ट्रिगर फ़ील्ड जोड़ना न भूलें. इसकी वैल्यू unconditional {} होनी चाहिए.
  2. कॉन्टेक्स्ट के हिसाब से ट्रिगर करने वाली ऐसी सुविधा लागू करें जो उपयोगकर्ता के मैसेज में ऐड-ऑन चुनने पर, मैसेज यूज़र इंटरफ़ेस (यूआई) बनाए.
  3. उपयोगकर्ता के यूज़र इंटरफ़ेस (यूआई) इंटरैक्शन का जवाब देने के लिए, उससे जुड़े ज़रूरी फ़ंक्शन लागू करें.

कॉन्टेक्स्ट के हिसाब से ट्रिगर करना

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

कॉन्टेक्स्ट के हिसाब से ट्रिगर होने की सुविधा, आपके ऐड-ऑन के प्रोजेक्ट के मेनिफ़ेस्ट में तय की जाती है. ट्रिगर की परिभाषा से Gmail को यह पता चलता है कि किन शर्तों के तहत कौनसा ट्रिगर फ़ंक्शन चालू करना है. उदाहरण के लिए, यह मेनिफ़ेस्ट स्निपेट, बिना शर्त वाला ट्रिगर सेट करता है. यह ट्रिगर, मैसेज खोले जाने पर ट्रिगर फ़ंक्शन onGmailMessageOpen() को कॉल करता है:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

कॉन्टेक्स्ट के हिसाब से ट्रिगर होने वाला फ़ंक्शन

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

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

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

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

ट्रिगर फ़ंक्शन को, बनाए गए Card ऑब्जेक्ट की एक शृंखला बनानी और दिखानी होगी. उदाहरण के लिए, यहां एक ऐसा ऐड-ऑन बनाया गया है जिसमें सिर्फ़ एक कार्ड है. इस कार्ड में, मैसेज का विषय और भेजने वाले का नाम दिखता है:

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }