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

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

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

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

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

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

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

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

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

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

عند تحديد النطاقات صراحةً، اختَر دائمًا مجموعة النطاقات الأقل تساهلاً. على سبيل المثال، لا تجعل الإضافة تطلب إذن الوصول الكامل إلى "تقويم Google" للمستخدم باستخدام النطاق 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 بسبب تعذُّر الحصول على إذن، يمكنك عرض بطاقة توضّح ذلك وطلب من المستخدم التحقّق من معلومات الحساب المستخدَمة.

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

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

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

    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" على إجراء ذلك تلقائيًا عند الضرورة.