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

يمكن أن توفّر إضافات Google Workspace التي توسّع نطاق Gmail واجهة مستخدم عندما يقرأ المستخدم الرسائل. يتيح ذلك للإضافات تنفيذ المهام تلقائيًا التي تستجيب لمحتوى الرسالة، مثل عرض معلومات إضافية ذات صلة بالرسالة أو استردادها أو إرسالها.

الوصول إلى واجهة مستخدم رسائل إضافة Google Workspace

هناك طريقتان لعرض واجهة مستخدم الرسائل الخاصة بإحدى الإضافات. الطريقة الأولى هي فتح رسالة أثناء فتح الإضافة (على سبيل المثال، عند عرض الصفحة الرئيسية للإضافة في نافذة البريد الوارد في Gmail). الطريقة الثانية هي بدء الإضافة أثناء عرض رسالة.

في كلتا الحالتين، تنفّذ الإضافة دالة التشغيل السياقي المناسبة، والمحدّدة في بيان الإضافة. يتم تنفيذ المشغّل أيضًا إذا انتقل المستخدم إلى رسالة مختلفة بينما لا تزال الإضافة مفتوحة. تنشئ دالة التشغيل السياقي واجهة مستخدم الرسالة، ثم يعرضها Gmail للمستخدم.

إنشاء إضافة رسائل

يمكنك إضافة وظيفة الرسائل إلى إضافة باتّباع الخطوات العامة التالية:

1. أضِف الحقول المناسبة إلى بيان مشروع البرنامج النصي للإضافة، بما في ذلك النطاقات المطلوبة لوظيفة المراسلة. احرص على إضافة حقل مشغّل شرطي إلى ملف البيان، مع قيمة unconditional تساوي {}.
2. نفِّذ دالة مشغّل حسّاسة للسياق تنشئ واجهة مستخدم للرسالة عندما يختار المستخدم الإضافة في رسالة.
3. تنفيذ الدوال المرتبطة اللازمة للرد على تفاعلات المستخدم مع واجهة المستخدم

المشغّلات السياقية

لمساعدة المستخدمين أثناء قراءة الرسائل، يمكن للإضافات تحديد عامل تشغيل سياقي في بياناتها. عندما يفتح المستخدم رسالة Gmail (مع فتح الإضافة) تستوفي معايير التشغيل*، يتم تشغيل المشغّل. يؤدي تشغيل مشغّل تم تنشيطه إلى تنفيذ دالة مشغّل سياقية تنشئ واجهة مستخدم الإضافة وتعرضها في Gmail. عندئذٍ، يمكن للمستخدم بدء التفاعل معها.

يتم تحديد المشغّلات السياقية في بيان مشروع الإضافة. يحدّد تعريف المشغّل وظيفة المشغّل التي سيتم تشغيلها في أي ظروف. على سبيل المثال، يضبط مقتطف البيان التالي مشغّلاً غير مشروط يستدعي دالة المشغّل onGmailMessageOpen() عند فتح رسالة:

{
  ...
  "addOns": {

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

دالة التشغيل المستندة إلى السياق

يجب أن يتضمّن كل مشغّل سياقي دالة مشغّل مقابلة تنشئ واجهة مستخدم الإضافة. يمكنك تحديد هذه الدالة في حقل onTriggerFunction في ملف البيان. يمكنك تنفيذ هذه الدالة لقبول وسيطة كائن حدث الإجراء وعرض إما كائن Card واحد أو مصفوفة من كائنات Card.

عندما يتم تشغيل مشغّل سياقي لرسالة Gmail معيّنة، يتم استدعاء هذه الدالة وتمرير عنصر حدث إجراء إليها. تستخدم الدوال المشغِّلة غالبًا رقم تعريف الرسالة المقدَّم من خلال عنصر الحدث هذا للحصول على نص الرسالة وتفاصيل أخرى باستخدام خدمة Gmail في Apps Script. في معظم الحالات، يجب تفعيل نطاقات Gmail باستخدام رمز الدخول الذي يوفّره عنصر الحدث والدالة GmailApp.setCurrentMessageAccessToken(accessToken) قبل استخدام وظائف خدمة 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}