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

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

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

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

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

تنزيل Xcode

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

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

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

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

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

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

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

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

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

  1. أنشِئ معرّف مجموعة تطبيقات لتطبيقك من أجل التواصل مع MatterExtension.
    1. سجِّل الدخول إلى بوابة Apple Developer.
    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، انتقِل إلى لوحة بيانات أداة اختيار المشاريع واختَر المشروع الذي تريد استخدامه لإنشاء بيانات اعتماد 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 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 API لنظام التشغيل iOS، يجب أولاً تسجيل الدخول إلى Google Home Developers.

سجِّل الدخول الآن.

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

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

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

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

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

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

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

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

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

    1. لتشغيل نموذج التطبيق ونشره بنجاح على الأجهزة باستخدام شهادات المطوّر وملفات التعريف، عليك تقديم معرّف حزمة فريد. يجب أن يكون هذا المعرّف هو نفسه المرتبط ببيانات اعتماد عميل OAuth (انظر أعلاه).
    2. في مساحة الروابط في Xcode، اختَر ملف مشروع GoogleHomeAPISampleIOS لتعديل إعدادات المشروع.
    3. انقر على علامة التبويب Signing and Capabilities (التوقيع والإمكانات) في أعلى الصفحة واختَر الهدف GoogleHomeAPISampleIOS على يمين الصفحة ضمن قسم TARGETS (الأهداف).
    4. اختَر حقل "معرّف الحزمة" (Bundle Identifier) في قسم التوقيع (Signing) وأدخِل المعرّف الفريد للتطبيق.
    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
  ...
}