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

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

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

تأكَّد من توفّر الحد الأدنى من المتطلبات لاستخدام Home APIs لنظام التشغيل iOS.

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

تنزيل Xcode

لاختبار التطبيق، يجب استيفاء ما يلي:

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

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

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

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

أولاً، يتطلّب التطبيق تفعيل إمكانية App Attest. نتيجةً لذلك، لا يمكن نشرها على أجهزة المحاكي. يتطلّب ذلك إنشاء ملف توفير يحتوي على إذن 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 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، انقر على ملف (File) > فتح (Open)، ثم اختَر GoogleHomeAPISampleIOS.xcodeproj في جذر المستودع الذي تم استنساخه.

إعداد حزمة تطوير البرامج (SDK)

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

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

لتنزيل حزمة تطوير البرامج (SDK) لنظام التشغيل iOS الخاصة بواجهات برمجة التطبيقات Home، يجب أولاً تسجيل الدخول إلى 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)، ورقم مشروع Cloud الذي يتوافق مع مشروعك على السحابة الإلكترونية، والحقل GIDTeamID بمعرّف فريق المطوّرين على Apple لحساب المطوّر المستخدَم أثناء عملية التسجيل في OAuth.

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

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

  13. أضِف إذن الوصول إلى مجموعات التطبيقات.

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

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

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

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

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

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

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

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