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

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

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

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

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

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

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

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

إبقاء النطاقات ضيّقة

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

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

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

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

أفضل الممارسات المتعلّقة بإضافات Google Workspace

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

استخدام بضع بطاقات فقط

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

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

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

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

البساطة في البطاقات

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

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

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

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

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

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

    Logger.log(response.printJson());

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

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

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

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

إبقاء onCreateFunction مضيئًا

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

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

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

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

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