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

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];
  }