توسيع واجهة مستخدم الرسالة

يمكن أن توفِّر إضافات 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 معينة، فإنه يُطلق على هذا وتمريره كائن حدث الإجراء. تستخدم الدوال المشغّلة عادةً معرّف الرسالة الذي يوفّره كائن الحدث هذا للحصول على نص الرسالة والتفاصيل الأخرى باستخدام خدمة 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];
  }