صفحات رئيسية

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

تتيح لك صفحات البداية عرض محتوى غير سياقي، على غرار تطبيقات Google في اللوحة الجانبية للوصول السريع (Google Keep و"تقويم Google" و"مهام Google"). يمكن أن توفّر الصفحات الرئيسية أيضًا نقطة بداية أولية عندما يفتح المستخدم الإضافة لأول مرة، وهي مفيدة لتعليم المستخدمين الجدد كيفية التفاعل مع الإضافة.

حدِّد صفحة رئيسية للإضافة من خلال تحديدها في ملف البيان الخاص بمشروعك وتنفيذ دالة واحدة أو أكثر من دوال homepageTrigger (راجِع إعدادات الصفحة الرئيسية). إذا كانت الإضافة توسّع نطاق Google Chat، ستظهر صفحتها الرئيسية في علامة التبويب الصفحة الرئيسية ضمن رسالة مباشرة على الخاص مع تطبيق Chat، ويتم ضبطها في Google Cloud Console بدلاً من ملف البيان (راجِع ضبط صفحة رئيسية في Chat).

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

يتم عرض الصفحة الرئيسية للإضافة في الحالات التالية:

• عند فتح الإضافة لأول مرة في التطبيق المضيف (بعد منح الإذن)، أو عندما يفتح المستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة بين شخصين مع تطبيق Chat في Chat
• عندما ينتقل المستخدم من سياق ذي صلة إلى سياق غير ذي صلة أثناء فتح الإضافة على سبيل المثال، من تعديل حدث في "تقويم Google" إلى "تقويم Google" الرئيسي.
• عندما ينقر المستخدم على زر الرجوع عدة مرات لإزالة كل بطاقة أخرى من الحِزم الداخلية
• عندما يؤدي تفاعل واجهة المستخدم في بطاقة غير سياقية إلى طلب Navigation.popToRoot.

ننصحك بتصميم صفحة رئيسية. في حال عدم تحديد أي بطاقة، سيتم استخدام بطاقة عامة تحتوي على اسم الإضافة عندما ينتقل المستخدم إلى الصفحة الرئيسية.

إعدادات الصفحة الرئيسية

تستخدِم إضافات Google Workspace الحقل addOns.common.homepageTrigger من أجل ضبط المحتوى التلقائي للصفحة الرئيسية (غير السياقي) للإضافة في التطبيقات المضيفة ضمن بيان الإضافة:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

• runFunction: اسم دالة "برمجة تطبيقات Google" التي يستدعيها إطار عمل إضافات Google Workspace لعرض بطاقات الإضافة على الصفحة الرئيسية. هذه الدالة هي دالة مشغّل الصفحة الرئيسية. يجب أن تنشئ هذه الدالة صفيفًا من عناصر Card التي تشكّل واجهة مستخدم الصفحة الرئيسية وتعرضه. إذا تم عرض أكثر من بطاقة واحدة، يعرض التطبيق المضيف عناوين البطاقات في قائمة يمكن للمستخدم الاختيار منها (راجِع عرض بطاقات متعددة).

• ‫enabled: تحدّد ما إذا كان يجب تفعيل بطاقات الصفحة الرئيسية لهذا النطاق. هذا الحقل اختياري، والقيمة التلقائية له هي true. إذا تم ضبط هذه السياسة على false، سيتم إيقاف بطاقات الصفحة الرئيسية لجميع المضيفين (ما لم يتم إلغاء هذا الإعداد للمضيف المعنيّ، يُرجى الاطّلاع على الإعدادات الخاصة بالمضيف).

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

بالإضافة إلى الإعدادات الشائعة، تتوفّر عمليات إلغاء منظَّمة بشكل مماثل لكل مضيف في إعدادات كل تطبيق مضيف، وذلك في addOns.gmail.homepageTrigger وaddOns.calendar.homepageTrigger وغيرها من المشغّلات الخاصة بالمضيف.

يعرض المثال التالي ملف بيان تم فيه تحديد مشغّل شائع للصفحة الرئيسية، ولكن تم استبداله بدوال مخصّصة لـ "تقويم Google" وDrive، وتم إيقافه في Gmail. في هذا الإعداد، لا يتم تنفيذ الدالة buildHomePage الشائعة أبدًا لأنّه يتم إما إلغاؤها أو يكون المضيف غير مفعّل.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

إنّ مقتطف البيان التالي مكافئ للمثال السابق، على الرغم من حذف السمة التلقائية homepageTrigger وإعدادات Gmail:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

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

ضبط الصفحة الرئيسية في Chat

على عكس تطبيقات المضيفة الأخرى في Google Workspace، لا تعرض الإضافات التي توسّع Chat صفحة رئيسية في لوحة الوصول السريع على يسار الشاشة، ولا تستخدم addOns.common.homepageTrigger في ملف البيان. بدلاً من ذلك، يعرض Chat صفحتك الرئيسية كبطاقة في علامة التبويب الصفحة الرئيسية ضمن رسالة مباشرة على الخاص مع تطبيق Chat.

لتفعيل مشغّل "صفحة التطبيق" وضبط إعداداته لإضافة Chat في Google Cloud Console، اتّبِع الخطوات التالية:

1. في Google Cloud Console، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API > الإعدادات.

   الانتقال إلى إعدادات Google Chat API

2. ضِمن الميزات التفاعلية، تأكَّد من تفعيل تفعيل الميزات التفاعلية، ثم ضَع علامة في مربّع الاختيار تفعيل "الصفحة الرئيسية للتطبيق".

3. ضمن إعدادات الربط > المشغّلات، حدِّد معالج "الصفحة الرئيسية للتطبيق" في حقل الصفحة الرئيسية للتطبيق استنادًا إلى بنية الإضافة:

   • HTTP: أدخِل عنوان URL لنقطة نهاية HTTPS التي تعالج طلبات "الصفحة الرئيسية للتطبيق" (أو اتركه فارغًا لكي يتلقّى عنوان URL لنقطة نهاية HTTP الشائعة جميع الأحداث).
   • برمجة تطبيقات Google: أدخِل اسم دالة رد الاتصال في "برمجة تطبيقات Google" التي تنشئ بطاقة الصفحة الرئيسية وتعرضها (القيمة التلقائية هي onAppHome).

4. انقر على حفظ.

عندما يفتح مستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة مع تطبيق Chat، يرسل Chat حدث تشغيل الصفحة الرئيسية للتطبيق إلى نقطة النهاية أو الدالة. لعرض الصفحة الرئيسية، عليك عرض عنصر RenderActions يتضمّن إجراء التنقّل pushCard (أو استخدام updateCard عند تعديل الصفحة الرئيسية استجابةً للنقر على زر في بطاقة الصفحة الرئيسية):

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

لمزيد من التفاصيل حول التعامل مع مشغّلات Chat وإرجاع الإجراءات، يُرجى الاطّلاع على تلقّي تفاعلات المستخدمين والردّ عليها.

عناصر أحداث الصفحة الرئيسية

عند استدعاء دالة مشغّل الصفحة الرئيسية (runFunction) أو نقطة نهاية "الصفحة الرئيسية للتطبيق" الموضّحة سابقًا، يتم تمرير عنصر حدث يحتوي على بيانات من سياق الاستدعاء.

لا تتضمّن عناصر أحداث الصفحة الرئيسية معلومات عن الأدوات أو معلومات سياقية. تتضمّن المعلومات التي يتم تمريرها حقول عنصر الحدث الشائع التالية:

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• ‫commonEventObject.userLocale وcommonEventObject.userTimezone (اطّلِع على الوصول إلى لغة المستخدم والمنطقة الزمنية للحصول على معلومات حول القيود).

في Chat، يتضمّن عنصر حدث "صفحة التطبيق الرئيسية" أيضًا الحقل chat الذي يتضمّن معلومات عن المستخدم ووقت التفاعل:

• chat.user: مستخدم Chat الذي فتح علامة التبويب الصفحة الرئيسية
• chat.eventTime: الطابع الزمني الذي فتح فيه المستخدم علامة التبويب الصفحة الرئيسية.

اطّلِع على عنصر الحدث لمزيد من التفاصيل.

البطاقات الأخرى غير السياقية

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

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