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

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

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

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

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

تنزيل Xcode

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

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

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

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

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

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

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

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

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

  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 APIs

يحتاج تطبيقك إلى معرّف عميل OAuth لتعريف نفسه على نظام المصادقة الخلفي من Google. بالنسبة إلى أجهزة iOS والتطبيقات، يجب ضبط نوع تطبيق معرّف عميل OAuth على iOS. سيُجري التطبيق أيضًا طلبات إلى Home API. لتفعيل هذه الوظيفة، يجب تفعيل واجهة برمجة التطبيقات في المشروع 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 APIs

فعِّل إمكانية الوصول إلى Home APIs.

  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) الخاصة بـ Home APIs لنظام التشغيل iOS، يجب أولاً تسجيل الدخول إلى 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

  8. اضبط نطاق OAuth في GoogleHomeAPISampleIOS.swift. تلقائيًا، يستخدم رمز المصدر للتطبيق النموذجي النطاق https://www.googleapis.com/auth/home.platform.v2. تخضع العديد من الميزات في التطبيق النموذجي للنطاق home.platform.v2 وتتطلّب موافقة الشريك للوصول إليها. لتشغيل نموذج التطبيق باستخدام النطاق العادي https://www.googleapis.com/auth/home.platform.selected.devices ، افتح GoogleHomeAPISampleIOS.swift وغيِّر homePlatformOAuthScope في Home.configure إلى HomePlatformOAuthScope.v1:

    Home.configure {
  $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
  $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
  ...
}