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

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

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

نشجعك على اتباع أفضل الممارسات التالية لجميع الإضافات التي تقوم بتطويرها.

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

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

توسيع نطاق Google Workspace وعدم تكراره

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

تضييق النطاقات

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

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

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

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

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

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

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

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

تجنب الدافع لإنشاء بطاقات أكثر من اللازم.

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

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

استخدام البطاقات بسيطة

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

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

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

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

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

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

    Logger.log(response.printJson());

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

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

أفضل ممارسات مكالمات الفيديو في التقويم

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

إبقاء مصباح onCreateFunction

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

استخدام حقول ConferenceData مناسبة لبيانات مكالمات الفيديو

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

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

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