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

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

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

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

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

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

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

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

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

الحفاظ على نطاق ضيق

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Logger.log(response.printJson());

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

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

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

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

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

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

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

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

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

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