أفضل الممارسات

يمكنك تحسين تجربة المستخدمين بشكل عام من خلال اتّباع أدلة تصميم الإضافات التالية.

أفضل الممارسات العامة

ننصحك باتّباع أفضل الممارسات التالية لجميع الإضافات التي تطوّرها.

تحديد ملكية الإضافة قبل البدء

يتم تحديد الإضافات من خلال مشاريع Apps Script، والتي يجب أن يملكها حساب محدّد أو أن يتم وضعها في مساحة تخزين سحابي مشتركة. قبل كتابة رمز إحدى الإضافات، حدِّد الحساب الذي يجب أن يمتلك المشروع والحساب الذي يعمل كناشر له. حدِّد أيضًا الحسابات التي ستعمل كمتعاونين، وتأكَّد من أنّ هذه الحسابات لديها إذن الوصول إلى مشروع البرنامج النصي ومشروع Google Cloud المرتبط به.

توسيع نطاق Google Workspace، وليس تكراره

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

الحفاظ على نطاق الأذونات محدودًا

عند تحديد نطاقاتك بشكل صريح، اختَر دائمًا مجموعة النطاقات الأقل تساهلاً الممكنة. على سبيل المثال، لا تطلب الإضافة إذن الوصول الكامل إلى تقويم المستخدم باستخدام النطاق https://www.googleapis.com/auth/calendar إذا كانت تحتاج إلى إذن بالقراءة فقط. للحصول على إذن بالقراءة فقط، استخدِم النطاق https://www.googleapis.com/auth/calendar.readonly.

تجنُّب الاعتماد بشكل كبير على المكتبات

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

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

أفضل الممارسات لاستخدام إضافات Google Workspace

لا تنطبق أفضل الممارسات التالية إلا على إضافات Google Workspace واستخدام خدمة البطاقات.

استخدام عدد قليل من البطاقات

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

تجنَّب إنشاء بطاقات أكثر من اللازم.

استخدام وظائف إنشاء التطبيقات المصغّرة

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

الحفاظ على بساطة البطاقات

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

استخدام بطاقات الخطأ

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

كتابة الاختبارات ورسائل الاختبار

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

عند استخدام دوال معاودة الاتصال بالإجراءات، عليك عادةً إنشاء عنصر استجابة. يمكنك استخدام عبارات مثل ما يلي للتأكّد من أنّ الردود يتم إنشاؤها بشكل صحيح:

    Logger.log(response.printJson());

يمكنك تشغيل دوال الاختبار التي تنشئها مباشرةً من محرّر Apps Script باستخدام قائمة تشغيل. عندما يتوفّر لديك إضافة قابلة للاستخدام، احرص على تثبيت الإصدار غير المنشور لتتمكّن من اختبارها.

استخدِم بيانات اختبار مناسبة لكل تطبيق مضيف يوسّعه الملحق. على سبيل المثال، إذا كانت الإضافة توسّع نطاق Gmail، من المحتمل أن تحتاج إلى بعض الرسائل الإلكترونية التجريبية ومعرّفات الرسائل الخاصة بها حتى تتمكّن من التأكّد من أنّ الإضافة تعمل على النحو المتوقّع عند تقديم محتوى رسائل مختلف. يمكنك الحصول على معرّف الرسالة لرسالة معيّنة من خلال إدراج الرسائل باستخدام طريقة Gmail API users.messages.list أو من خلال استخدام خدمة Gmail في Apps Script.

أفضل الممارسات المتعلّقة باجتماعات الفيديو في "تقويم Google"

إذا كان المكوّن الإضافي يدمج خيارات مكالمات الفيديو في تقويم تابع لجهة خارجية في "تقويم Google"، اتّبِع أفضل الممارسات الإضافية التالية:

إبقاء مصباح onCreateFunction مضاءً

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

استخدام حقول ConferenceData المناسبة لبيانات المؤتمر

عند إنشاء عناصر ConferenceData، يمكنك ملؤها بتفاصيل حول المؤتمر (رموز الدخول وأرقام الهواتف وأرقام التعريف الشخصية ومعرّفات الموارد المنتظمة وما إلى ذلك). احرص على استخدام الحقل EntryPoint المناسب لهذه المعلومات. لا تضع هذه التفاصيل في حقل الملاحظات ConferenceData.

عدم إلحاق تفاصيل مكالمة الفيديو بحدث "تقويم Google"

لا تحتاج الإضافة إلى إضافة معلومات حول المؤتمرات التي تم إنشاؤها من خلال جهات خارجية إلى وصف حدث "تقويم Google". يُجري "تقويم Google" ذلك تلقائيًا عند الضرورة.