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

يمكن أن توفر إضافات 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];
  }