إنشاء تطبيق iOS تجريبي

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

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

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

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

تنزيل Xcode

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

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

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

  • نظام التشغيل macOS Sonoma أو إصدار أحدث
  • الإصدار 15.3 من Xcode أو إصدار أحدث

إنشاء ملفات إعداد نشر Apple

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

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

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

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

  1. أنشئ معرّف مجموعة تطبيقات لتطبيقك للتواصل مع MatterExtension.
    1. سجِّل الدخول إلى بوابة المطوّرين في Apple.
    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. الحقول الأخرى اختيارية ويمكن تركها فارغة.
    3. انقر على إنشاء، وسجِّل معرّف العميل الذي تم إنشاؤه أو تنزيل ملف PLIST. وسيتم استخدام هذا الإجراء لاحقًا لتفعيل وظائف تدفق الأذونات. لمزيد من المعلومات، يُرجى الاطّلاع على قسم إنشاء بيانات اعتماد التفويض.

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

فعِّل الوصول إلى واجهات برمجة تطبيقات 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) لـ Home APIs على نظام التشغيل iOS، يجب أولاً تسجيل الدخول إلى Google Home Developers.

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

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

  1. في لوحة التنقّل في Xcode، اختَر ملف GoogleHomeAPISampleIOS لتعديل إعدادات المشروع.

    إعداد نموذج تطبيق حزمة SDK

  2. انقر على علامة التبويب الإعدادات العامة في أعلى الصفحة واختَر الهدف GoogleHomeAPISampleIOS على يمين الصفحة.

  3. انتقِل للأسفل إلى أن يظهر لك قسم الإطارات والمراجع والمحتوى المضمّن. من المفترض أن يظهر لك إطارا عمل Home API مدرَجين.

  4. في عمود التضمين، اختَر التضمين والتوقيع لملف GoogleHomeSDK.xcframework. يجب ترك الإطار الآخر، GoogleHomeTypes.xcframework، على القيمة عدم التضمين.

  5. في أسفل القائمة، انقر على رمز +.

  6. ابحث عن SafariServices.framework وانقر على إضافة عندما يُطلب منك ذلك. تأكَّد من ضبط عمود دمج على عدم الدمج لهذه الإدخال.

    التضمين والتوقيع

  7. انقر على MatterAddDeviceExtension ضمن الاستهداف لتعديل استهدافه.

  8. انتقِل للأسفل إلى أن يظهر لك قسم الإطارات والمراجع. من المفترض أن يظهر لك GoogleHomeSDK.xcframework.

  9. في عمود التضمين، اختَر عدم التضمين.

  10. ضبط معرِّفَي العميل للمطوّر وOAuth:

    1. في لوحة التنقّل، ابحث عن المجلد GoogleHomeAPISampleIOS وافتَح الملف Info.plist لتعديله.

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

  12. ضبط نظام التصميم:

    إضافة علامات الربط

    1. في لوحة التنقّل في Xcode، انقر على GoogleHomeAPISampleIOS ملف المشروع لتعديل إعدادات المشروع.
    2. انقر على علامة التبويب إعدادات الإصدار في أعلى الصفحة واختَر الهدف GoogleHomeAPISampleIOS على يمين الصفحة ضمن القسم TARGETS (الاستهدافات).
    3. ابحث عن Other Linker Flags (علامات الربط الأخرى) وأضِف إدخالَين:
      • -lc++
      • -ObjC

  13. إضافة ميزة "إثبات ملكية التطبيق":

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

  14. أضِف ميزة مجموعات التطبيقات.

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

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

  15. تعديل معرِّف الحِزمة

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

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

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

    يتم إجراء هذه الإعدادات في الملفات التالية:

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