संदेश UI को विस्तृत करना

Google Workspace Gmail का इस्तेमाल करने वाले ऐड-ऑन की मदद से, उपयोगकर्ता का मैसेज पढ़ने पर उसे यूज़र इंटरफ़ेस मिल सकता है. इससे,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];
  }