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

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

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

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

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

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

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

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

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

لمساعدة المستخدمين في قراءة الرسائل، يمكن لإضافات 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 باستخدام رمز الدخول الذي يوفّره عنصر الحدث والدالة GmailApp.setCurrentMessageAccessToken(accessToken) قبل استخدام وظائف أخرى في خدمة Gmail.

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

يجب أن تنشئ دالة المشغّل مصفوفة من الكائنات التي تم إنشاؤها 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];
  }