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

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

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

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

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

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

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

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

محرک های متنی

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

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

{
  ...
  "addOns": {

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

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

تابع ماشه متنی

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

هنگامی که یک تریگر متنی برای یک پیام Gmail مشخص فعال می شود، این تابع را فراخوانی می کند و آن را یک شی رویداد اقدام ارسال می کند. اغلب توابع راه‌انداز از شناسه پیام ارائه‌شده توسط این شی رویداد برای دریافت متن پیام و سایر جزئیات با استفاده از سرویس 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();

توجه: در بیشتر موارد، قبل از استفاده از سایر توابع سرویس Gmail، باید دامنه های Gmail را با استفاده از نشانه دسترسی ارائه شده توسط شی رویداد و عملکرد 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];
  }