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

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

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

يمكنك إنشاء إضافة باستخدام "برمجة تطبيقات Google" أو HTTP. للمقارنة، شاهِد الفيديو "برمجة تطبيقات مقابل نقاط نهاية HTTP: أيهما يجب عليك اختياره؟ 🤔".

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

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

  • Gmail
  • تقويم Google
  • Google Chat
  • مستندات Google
  • Google Drive
  • Google Meet
  • جداول بيانات Google
  • العروض التقديمية من Google

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

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

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

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

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

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

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

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

لإنشاء مشروع في "برمجة التطبيقات"، يُرجى الاطّلاع على مشاريع البرامج النصية.

مشاريع Google Cloud

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

لإنشاء مشروع على Google Cloud، يُرجى الاطّلاع على إنشاء مشروع على Google Cloud.

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

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

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

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

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

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

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

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

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

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

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

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

بطاقات التركيب

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

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

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

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

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

أمر البناء

عند إنشاء بطاقة، يجب البدء من الأعلى. أي يجب استخدام ترتيب الإنشاء التالي:

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

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

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

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

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

التحقّق من نطاقات OAuth الخاصة بالإضافة

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

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

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

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

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

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

نشر الإضافة

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

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

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