إنشاء إضافات Google Workspace

تقدّم هذه الصفحة نظرة عامة حول كيفية تصميم وإكمال ونشر إضافات Google Workspace. توضّح هذه النظرة العامة الخطوات التالية:

1. حدِّد تطبيقات Google Workspace التي تريد أن تتوفّر فيها الإضافة للمستخدمين.
2. إعداد مشاريع الإضافة واختيار مالك ومتعاونين
3. تصميم مظهر الإضافة وسلوكها وضبطهما
4. أنشئ الإضافة.
5. تحقَّق من نطاقات OAuth الخاصة بإضافتك.
6. اختبِر الإضافة في تطبيق واحد أو أكثر من تطبيقات Google Workspace.
7. انشر الإضافة.

اختيار تطبيقات مضيفة في Google Workspace

يمكنك ضبط إضافات Google Workspace لتظهر في التطبيقات التالية المضيفة في Google Workspace:

• Gmail
• تقويم Google
• Google Chat (إصدار معاينة المطوّر)
• مستندات Google
• Google Drive
• جداول بيانات Google
• العروض التقديمية من Google

للتعرّف على كيفية إنشاء تطبيقات Google Workspace، اطّلِع على مقالة توسيع نطاق واجهة مستخدم Google Workspace.

إعداد مشاريع الإضافة واختيار مالك ومتعاونين

إذا أنشأت الإضافة في Apps Script، ستُنشئ مشروع Apps Script ومشروع Google Cloud. إذا أنشأت الإضافة بلغة غير برمجة تطبيقات Google، ما عليك سوى إنشاء مشروع على Google Cloud.

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

تحذير: إذا لم تُضِف متعاونين إلى مشاريعك الملحقة، من المهم نقل ملكيتها قبل إغلاق حساب المالك أو إزالته. بخلاف ذلك، قد تفقد إمكانية الوصول إلى رمز الإضافة وإعداداتها بالكامل.

مشاريع "برمجة تطبيقات Google"

يمكنك إنشاء ملفات مشروع "برمجة تطبيقات Google" لإضافة Chrome في مساحة تخزين سحابي مشترَكة حتى لا يكون لأي حساب واحد ملكية مطلقة. يضمن وضع ملف رمزبرمجي إضافي في مساحة تخزين سحابي مشتركة إمكانية وصول متعاونين متعدّدين إلى مشروع الرمز البرمجي.

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

لإنشاء مشروع على Apps Script، اطّلِع على مشاريع النصوص البرمجية.

مشاريع Google Cloud

ننصحك بإضافة متعاونين إلى مشروع الإضافة في سحابة Google. يساعد ذلك في ضمان إمكانية وصول أحد أفراد فريقك في أي وقت إلى إعدادات "سحابة Google" في الإضافة.

لإنشاء مشروع على Google Cloud، راجِع مقالة إنشاء مشروع على Google Cloud.

تصميم مظهر الإضافة وسلوكها وضبطهما

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

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

راجِع دليل أسلوب إضافات Google Workspace للحصول على إرشادات حول كيفية تصميم تجربت مستخدمي الإضافة.

ضبط ملف بيان الإضافة

بعد تصميم الإضافة، يمكنك البدء في تنفيذ التصميم في بيان الإضافة. في البيان، يمكنك ضبط معظم ملف تعريف الإضافة وسلوكها، بما في ذلك تطبيقات مضيف Google Workspace التي تمتد إليها الإضافة.

لمعرفة التفاصيل، يُرجى الاطّلاع على ملفات البيان الخاصة بإضافات Google Workspace.

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

ضبط مظهر تطبيق Google Chat وسلوكه

إصدار المطوّر: يتوفّر كجزء من برنامج إصدار المطوّر في Google Workspace، الذي يتيح الوصول المبكر إلى ميزات معيّنة.

إذا كنت قد صمّمت إضافة توفّر ميزات إضافية في Google Chat، عليك استخدام Google Chat API لضبط مظهر تطبيق Chat وطريقة عمله. للاطّلاع على الخطوات، راجِع مقالة ضبط تطبيق Google Chat.

إنشاء الإضافة

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

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

بطاقات الإنشاء

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

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

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

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

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

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

أمر الإنشاء

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

1. أنشئ التطبيق المصغّر.
2. أضِف التطبيق المصغّر إلى قسم البطاقة.
3. كرِّر هذه الخطوة إلى أن يتضمّن قسم البطاقة جميع التطبيقات المصغّرة.
4. أضِف قسم البطاقة إلى البطاقة.

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

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

الإجراءات العامة

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

اطّلِع على الإجراءات الشاملة للحصول على مزيد من التفاصيل.

التحقّق من نطاقات OAuth الإضافية

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

في المشاريع الإضافية، حدِّد بشكل صريح ملفّات تعريف النطاقات الإضافية لضمان استخدام الإضافة لأقل مجموعة من النطاقات permissive ممكنة. يمكنك تحديد النطاقات التي تستخدمها الإضافة في manifest الإضافة.

اطّلِع على النطاقات لمزيد من التفاصيل.

اختبار الإضافة

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

لبدء اختبار الإضافة، اطّلِع على الأدلة التالية:

• اختبار إضافات Google Workspace في "برمجة تطبيقات Google" وتصحيح الأخطاء فيها
• اختبار الإضافات HTTP في Google Workspace وتصحيح الأخطاء فيها
• اختبار الميزات التفاعلية لتطبيقات Google Chat

نشر الإضافة

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

يتم نشر إضافات Google Workspace في Google Workspace Marketplace. يجب أن تخضع المراجعات للإضافة المتاحة للجميع قبل نشرها.

اطّلِع على مقالة نشر إضافة Google Workspace للحصول على مزيد من التفاصيل.