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

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

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

يجب أن تنشئ دالة العنصر المشغِّل صفيفًا من عناصر 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];
  }