إنشاء نموذج تطبيق iOS

يستخدم تطبيق iOS النموذجي هذا واجهات برمجة تطبيقات Google Home. استخدِم هذا الدليل لإنشاء التطبيق وتشغيله للمرة الأولى.

المتطلبات الأساسية

تأكَّد من استيفاء الحد الأدنى من المتطلبات لاستخدام واجهات برمجة تطبيقات Home على أجهزة iOS.

لإنشاء التطبيق النموذجي وتثبيته، ستحتاج إلى جهاز كمبيوتر مثبَّت عليه الإصدار 15.3 أو إصدار أحدث من Xcode.

تنزيل Xcode

لاختبار التطبيق، ستحتاج إلى ما يلي:

  1. حساب Google.
  2. معرّف Apple ID مسجَّل في Apple Developer Program لإنشاء ملفات إعداد الأجهزة الفعلية. إذا لم يتم التسجيل بعد، سيتم تحصيل تكلفة إضافية وقد يستغرق إكمال التسجيل مدة تصل إلى 48 ساعة.
  3. جهاز iOS (وليس جهاز محاكاة) يعمل بنظام التشغيل iOS 16.4 أو إصدار أحدث تم إعداده باستخدام الحساب التجريبي.
  4. شبكة Wi-Fi
  5. مركز Google يدعم واجهات برمجة تطبيقات Home APIs.
  6. جهاز توجيه الحدود في Thread إذا كان جهازك يتطلّب Thread ولم يكن المركز يملك هذه الإمكانية
  7. نوع جهاز واحد على الأقل من الأنواع المتوافقة.

للتطوير، ستحتاج إلى جهاز Mac يستوفي المتطلبات التالية:

  • الإصدار macOS Sonoma أو إصدار أحدث
  • الإصدار Xcode 15.3 أو إصدار أحدث

إنشاء ملفات إعداد النشر على أجهزة Apple

أولاً، يتطلّب التطبيق تفعيل إمكانية App Attest. نتيجةً لذلك، لا يمكن نشره على أجهزة المحاكاة. يتطلّب ذلك إنشاء ملف إعداد يحتوي على إذن App Attest.

ثانيًا، يتطلّب ذلك تفعيل "مجموعات التطبيقات" للتواصل بين التطبيق وMatterExtension. يتطلّب ذلك تسجيل معرّف مجموعة تطبيقات.

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

في ما يلي الخطوات الدنيا المطلوبة لنشر تطبيق:

  1. أنشئ معرّف مجموعة تطبيقات لتطبيقك للتواصل مع MatterExtension.
    1. سجِّل الدخول إلى الـ Apple Developer Portal.
    2. أضِف معرّف مجموعة تطبيقات. على سبيل المثال، يمكن أن يكون بالتنسيق group.com.company.commissioning.
  2. سجِّل جهازك التجريبي في حساب المطوّر.

  3. أنشئ ملف إعداد لهدف تطبيقك.

    1. حدِّد معرّف حزمة تطبيق لتطبيقك. يجب أن يكون المعرّف فريدًا ووصفيًا. على سبيل المثال، يمكن أن يكون بالتنسيق com.company.HomeApiSample. سيتم استخدام هذا المعرّف في بقية هذا القسم.
    2. سجِّل معرّف التطبيق. عندما يُطلب منك ذلك، أضِف إمكانية App Attest ومجموعات التطبيقات.

    3. عدِّل معرّف التطبيق الذي تم إنشاؤه حديثًا واضبط إمكانية مجموعات التطبيقات لإضافة معرّف مجموعة التطبيقات المسجَّل.

    4. أنشئ ملف إعداد تطوير لتطوير تطبيقك. اربطه بمعرّف التطبيق الذي تم إنشاؤه حديثًا والأجهزة التجريبية التي تم اختيارها. تأكَّد من توفُّر شهادة مطوّر لتوقيع التطبيق.

  4. أنشئ ملف إعداد لهدف MatterExtension.

    1. حدِّد معرّف حزمة تطبيق لـ MatterExtension. يجب أن يكون المعرّف موروثًا من معرّف التطبيق. على سبيل المثال، يمكن أن يكون بالتنسيق com.company.HomeApiSample.MatterExtension.
    2. سجِّل معرّف التطبيق. عندما يُطلب منك ذلك، أضِف إمكانية مجموعة التطبيقات.
    3. عدِّل معرّف التطبيق الذي تم إنشاؤه حديثًا واضبط إمكانية مجموعات التطبيقات لإضافة معرّف مجموعة التطبيقات المسجَّل الذي تم إنشاؤه في الخطوات السابقة.
    4. أنشئ ملف إعداد تطوير لـ MatterExtension.

إنشاء معرّف عميل OAuth وتفعيل واجهات برمجة تطبيقات Home

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

إنشاء معرّف عميل OAuth

  1. في Google Cloud Console، انتقِل إلى لوحة بيانات اختيار المشروع واختَر المشروع الذي تريد استخدامه لإنشاء بيانات اعتماد OAuth.
  2. انتقِل إلى صفحة "واجهات برمجة التطبيقات والخدمات" من خلال النقر على زر القائمة في أعلى يمين الصفحة > عرض جميع المنتجات > واجهات برمجة التطبيقات والخدمات.
  3. في قائمة التنقّل، انقر على بيانات الاعتماد.

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

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

  5. في اللوحة الجانبية اليمنى، انقر على بيانات الاعتماد لإنشاء معرّف عميل OAuth.

    إعداد شاشة OAuth

    1. انقر على الزر إنشاء بيانات اعتماد ، ثم اختَر معرّف عميل OAuth.
      1. ضمن نوع التطبيق ، اختَر iOS.
    2. أدخِل معرّف الحزمة مع معرّف تطبيقك وApple Developer معرّف الفريق. الحقول الأخرى اختيارية ويمكن تركها فارغة.
    3. انقر على إنشاء ، وسجِّل معرّف العميل الذي تم إنشاؤه أو تنزيل ملف PLIST. سيتم استخدام هذا المعرّف لاحقًا لتفعيل وظيفة تدفق الأذونات. لمزيد من المعلومات، يُرجى الاطّلاع على قسم إنشاء بيانات اعتماد التفويض.

تفعيل واجهات برمجة تطبيقات Home

فعِّل إمكانية الوصول إلى واجهات برمجة تطبيقات Home.

  1. في علامة التبويب واجهات برمجة التطبيقات والخدمات ، انقر على واجهات برمجة التطبيقات والخدمات التي تم تفعيلها.
  2. انقر على تفعيل واجهات برمجة التطبيقات والخدمات في أعلى الصفحة.
  3. ابحث عن HOME API وانقر عليها.
  4. في صفحة التفاصيل Home API ، انقر على تفعيل.

تنزيل رمز المصدر

يتوفّر رمز المصدر للتطبيق النموذجي على GitHub.

انتقِل إلى المكان الذي تريد حفظ المشروع فيه، ثم استنسِخه:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

لتحميل المشروع على Xcode، انقر على ملف > فتح، ثم اختَر GoogleHomeAPISampleIOS.xcodeproj في جذر المستودع المستنسَخ.

إضافة حزمة تطوير البرامج (SDK) إلى المشروع

يتطلّب مشروع التطبيق النموذجي بعض المعلومات الإضافية لإنشائه. ويشمل ذلك إضافة ملفات حزمة تطوير البرامج (SDK) محليًا، وملء معلومات معرّف حساب المطوّر، وملء معرّف عميل OAuth.

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

لتنزيل حزمة تطوير البرامج (SDK) لنظام التشغيل iOS لواجهات برمجة تطبيقات Home، يجب أولاً تسجيل الدخول إلى Google Home Developers.

تسجيل الدخول الآن

اضبط مشروع Xcode للتطبيق النموذجي:

  1. فكِّك حزمة تطوير البرامج (SDK) التي تم تنزيلها في الدليل ThirdParty/GoogleHomeSDK بالنسبة إلى الدليل الجذري للمشروع.
  2. اضبط معرّفات المطوّر ومعرّف عميل OAuth:
    1. في لوحة التنقّل، ابحث عن المجلد GoogleHomeAPISampleIOS وافتح الملف Info.plist لتعديله.

  3. في الملف Info.plist ، املأ GIDClientID بمعرّف عميل OAuth (راجِع قسم إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth)، ورقم مشروع Cloud الذي يتطابق مع مشروعك على السحابة الإلكترونية، و GIDTeamID بمعرّف فريق Apple Developer لحساب المطوّر المستخدَم أثناء عملية تسجيل OAuth.

  4. أضِف إمكانية App Attest:

    1. في لوحة تنقّل Xcode، اختَر ملف مشروع GoogleHomeAPISampleIOS لتعديل إعدادات المشروع.
    2. انقر على علامة التبويب التوقيع والإمكانات في أعلى الصفحة، واختَر الهدف GoogleHomeAPISampleIOS على يمين الصفحة ضمن قسم الأهداف.
    3. أسفل علامة التبويب "التوقيع والإمكانات"، انقر على + إمكانية وابحث عن App Attest.
    4. انقر على App Attest لإضافتها. إذا لم تظهر هذه الإمكانية في نتائج البحث، قد يكون المشروع قد أضافها من قبل.

  5. أضِف إمكانية مجموعات التطبيقات.

    إضافة مجموعات التطبيقات

    1. انتقِل إلى مشروع GoogleHomeAPISampleIOS > هدف GoogleHomeAPISampleIOS.
    2. انقر على التوقيع والإمكانات > + إمكانية.
    3. اختَر إمكانية مجموعات التطبيقات.
    4. انقر على رمز + ضِمن مجموعات التطبيقات وأضِف معرّف "مجموعات التطبيقات" لتطبيقك الذي أضفته في Apple Developer Portal.
    5. كرِّر هذه الخطوات لهدف MatterAddDeviceExtension لإضافته إلى مجموعات التطبيقات.

  6. عدِّل معرّف الحزمة

    1. لتشغيل التطبيق النموذجي ونشره بنجاح على الأجهزة باستخدام شهادات المطوّر وملفات الإعداد، عليك تقديم معرّف حزمة فريد. يجب أن يكون هذا المعرّف هو نفسه المعرّف المرتبط ببيانات اعتماد عميل OAuth (راجِع أعلاه).
    2. في لوحة تنقّل Xcode، اختَر ملف مشروع GoogleHomeAPISampleIOS لتعديل إعدادات المشروع.
    3. انقر على علامة التبويب التوقيع والإمكانات في أعلى الصفحة، واختَر الهدف GoogleHomeAPISampleIOS على يمين الصفحة ضمن قسم الأهداف.
    4. اختَر حقل "معرّف الحزمة" في قسم التوقيع وأدخِل المعرّف الفريد للتطبيق.
    5. اختَر ملف الإعداد المرتبط بهذه الحزمة أو ثبِّته مع الأذونات المطلوبة.
    6. كرِّر هذه الخطوات لهدف MatterAddDeviceExtension لإدخال معرّف الحزمة للإضافة واستيراد ملف الإعداد المسجَّل.

  7. عدِّل معرّف مجموعة التطبيقات المسجَّل في الرمز.

    1. يجب أن يضبط التطبيق مثيل حزمة تطوير البرامج (SDK) لاستخدام معرّف مجموعة التطبيقات لميزات مثل إعداد الجهاز. عدِّل التطبيق لاستخدام معرّف مجموعة التطبيقات المسجَّل في Apple Developer Portal من خلال البحث عن السلسلة HOME_API_TODO_ADD_APP_GROUP واستبدال كل مثيل بها.

    يتم إجراء عمليات الضبط هذه في الملفات التالية:

    • GoogleHomeAPISampleIOS.swift عند إعداد حزمة تطوير البرامج (SDK)
    • RequestHandler.swift
    • CommissioningManager.swift