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

يمكن أن توفّر إضافات 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 للبيان. يمكنك تنفيذ هذه الدالة لقبول وسيطة كائن event event وعرض إما كائن 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];
  }