گسترش رابط کاربری پیام

افزونه‌های Google Workspace که Gmail را گسترش می‌دهند، می‌توانند هنگام خواندن پیام‌ها توسط کاربر، یک رابط کاربری ارائه دهند. این به افزونه‌های Google Workspace اجازه می‌دهد تا وظایفی را که به محتوای پیام پاسخ می‌دهند، مانند نمایش، بازیابی یا ارسال اطلاعات اضافی مربوط به پیام، خودکار کنند.

دسترسی به رابط کاربری پیام افزونه

دو راه برای مشاهده رابط کاربری پیام یک افزونه وجود دارد. راه اول باز کردن یک پیام در حالی است که افزونه از قبل باز است (برای مثال، هنگام مشاهده صفحه اصلی افزونه در پنجره صندوق ورودی Gmail). راه دوم شروع افزونه هنگام مشاهده یک پیام است.

هر دو حالت باعث می‌شوند افزونه، تابع محرک زمینه‌ای مربوطه را که در مانیفست افزونه تعریف شده است، اجرا کند. این محرک همچنین در صورتی که کاربر در حالی که افزونه هنوز باز است، به پیام دیگری سوئیچ کند، اجرا می‌شود. تابع محرک زمینه‌ای، رابط کاربری پیام را برای آن پیام می‌سازد که سپس جیمیل آن را به کاربر نمایش می‌دهد.

ساخت افزونه پیام

با دنبال کردن این مراحل کلی می‌توانید قابلیت پیام‌رسانی را به یک افزونه اضافه کنید:

1. فیلدهای مناسب را به مانیفست پروژه اسکریپت افزونه، از جمله محدوده‌های مورد نیاز برای عملکرد پیام، اضافه کنید. حتماً یک فیلد تریگر شرطی با مقدار unconditional {} به مانیفست اضافه کنید.
2. یک تابع محرک زمینه‌ای پیاده‌سازی کنید که وقتی کاربر افزونه را در یک پیام انتخاب می‌کند، یک رابط کاربری پیام ایجاد کند.
3. توابع مرتبط مورد نیاز برای پاسخ به تعاملات رابط کاربری کاربر را پیاده‌سازی کنید.

محرک‌های زمینه‌ای

برای ارائه کمک به کاربران هنگام خواندن پیام‌ها، افزونه‌های Google Workspace می‌توانند یک محرک زمینه‌ای را در مانیفست‌های خود تعریف کنند. وقتی کاربر یک پیام Gmail (با افزونه باز) را باز می‌کند که معیارهای محرک را برآورده می‌کند ، محرک فعال می‌شود. یک محرک فعال شده، یک تابع محرک زمینه‌ای را اجرا می‌کند که رابط کاربری افزونه را می‌سازد و آن را برای نمایش به Gmail برمی‌گرداند. در آن مرحله، کاربر می‌تواند تعامل با آن را آغاز کند.

محرک‌های زمینه‌ای در مانیفست پروژه افزونه شما تعریف می‌شوند. تعریف محرک به جیمیل می‌گوید که تحت چه شرایطی کدام تابع محرک را فعال کند. برای مثال، این قطعه مانیفست یک محرک غیرشرطی تنظیم می‌کند که هنگام باز شدن یک پیام، تابع محرک onGmailMessageOpen() را فراخوانی می‌کند:

{
  ...
  "addOns": {

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

در حال حاضر، تنها نوع تریگر متنی موجود، نوع unconditional است که برای همه ایمیل‌ها صرف نظر از محتوا، تریگر می‌شود.

تابع محرک زمینه‌ای

هر تریگر زمینه‌ای باید یک تابع تریگر متناظر داشته باشد که رابط کاربری افزونه شما را می‌سازد. شما این تابع را در فیلد onTriggerFunction در مانیفست خود مشخص می‌کنید. شما این تابع را برای پذیرش یک آرگومان شیء رویداد اکشن و بازگرداندن یک شیء Card یا آرایه‌ای از اشیاء Card پیاده‌سازی می‌کنید.

وقتی یک تریگر زمینه‌ای برای یک پیام Gmail مشخص فعال می‌شود، این تابع را فراخوانی کرده و یک شیء رویداد action به آن ارسال می‌کند. اغلب توابع تریگر از شناسه پیام ارائه شده توسط این شیء رویداد برای دریافت متن پیام و سایر جزئیات با استفاده از سرویس Gmail مربوط به Apps Script استفاده می‌کنند. به عنوان مثال، تابع تریگر شما می‌تواند با استفاده از این توابع، محتوای پیام را استخراج کند:

  // 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();

نکته: در بیشتر موارد، قبل از استفاده از سایر توابع سرویس جیمیل ، باید با استفاده از توکن دسترسی ارائه شده توسط شیء رویداد و تابع GmailApp.setCurrentMessageAccessToken(accessToken) دامنه‌های جیمیل را فعال کنید.

سپس تابع تریگر می‌تواند روی این داده‌ها عمل کند و اطلاعات مورد نیاز برای رابط کاربری را استخراج کند. برای مثال، افزونه‌ای که اعداد فروش را خلاصه می‌کند، می‌تواند ارقام فروش را از بدنه پیام جمع‌آوری کرده و آنها را برای نمایش در یک کارت سازماندهی کند.

تابع تریگر باید آرایه‌ای از اشیاء 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];
  }