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

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

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

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

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

تنزيل Xcode

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

  1. حساب Google.
  2. يجب أن يكون لديك معرّف Apple مسجَّل في برنامج 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

يحتاج تطبيقك إلى معرّف عميل 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.

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

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

يتوفّر الرمز المصدري لتطبيق Sample App على 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 لتطبيق Sample App باتّباع الخطوات التالية:

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

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

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

    1. في لوحة التنقّل في Xcode، اختَر ملف المشروع GoogleHomeAPISampleIOS لتعديل إعدادات المشروع.
    2. انقر على علامة التبويب التوقيع والإمكانات في أعلى الصفحة، ثم اختَر GoogleHomeAPISampleIOS المستهدف على الجانب الأيمن ضمن قسم TARGETS (الاستهدافات).
    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 المستهدف على الجانب الأيمن ضمن قسم 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