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

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

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

يمكنك إنشاء إضافة باستخدام Apps Script أو HTTP. للمقارنة، شاهِد الفيديو "Apps Script vs. HTTP endpoints: Which should you choose? 🤔".

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

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

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

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

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

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

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

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

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

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

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

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

مشاريع Google Cloud

ننصحك بإضافة متعاونين إلى مشروع 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 المقابل.

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

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

أمر البناء

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

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

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

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

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

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

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

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

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

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

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

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

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

نشر الإضافة

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

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

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