برنامه نمونه iOS را بسازید

این برنامه‌ی نمونه‌ی iOS از APIهای گوگل هوم استفاده می‌کند. از این راهنما برای ساخت و اجرای برنامه برای اولین بار استفاده کنید.

پیش‌نیازها

مطمئن شوید که حداقل شرایط لازم برای استفاده از APIهای Home برای iOS را دارید.

برای ساخت و نصب برنامه نمونه، به رایانه‌ای نیاز دارید که Xcode نسخه ۱۵.۳+ روی آن نصب شده باشد.

دانلود Xcode

برای آزمایش برنامه، به موارد زیر نیاز دارید:

  1. یک حساب گوگل .
  2. یک شناسه اپل (Apple ID) که در برنامه توسعه‌دهندگان اپل (Apple Developer Program) ثبت شده باشد تا فایل‌های پیکربندی فیزیکی دستگاه را ایجاد کند. اگر قبلاً ایجاد نشده باشد، ثبت‌نام هزینه اضافی دارد و ممکن است تا ۴۸ ساعت طول بکشد.
  3. یک دستگاه iOS (نه شبیه‌ساز) که iOS 16.4+ روی آن نصب شده و حساب آزمایشی روی آن تنظیم شده باشد.
  4. یک شبکه وای‌فای.
  5. یک مرکز گوگل که از API های Home پشتیبانی می‌کند .
  6. یک روتر مرزی Thread اگر دستگاه شما به Thread نیاز دارد و هاب شما این قابلیت را ندارد.
  7. حداقل یک نوع دستگاه پشتیبانی شده .

برای توسعه، به مکی نیاز دارید که شرایط زیر را داشته باشد:

  • macOS Sonoma یا بالاتر
  • ایکس‌کد ۱۵.۳ یا بالاتر

ایجاد فایل‌های پیکربندی استقرار اپل

اولاً، یک برنامه نیاز دارد که قابلیت App Attest فعال باشد. در نتیجه، نمی‌توان آن را روی دستگاه‌های شبیه‌ساز مستقر کرد. این امر مستلزم آن است که شما یک پروفایل تأمین‌کننده با مجوز App Attest ایجاد کنید.

دوم، برای ارتباط بین برنامه و MatterExtension ، لازم است که گروه‌های برنامه فعال باشند. این امر مستلزم ثبت یک شناسه گروه برنامه است.

برای جزئیات بیشتر، به بخش «ایجاد یک نمایه توسعه تأمین‌کننده» در اپل در مورد «نمایه‌های تأمین‌کننده» مراجعه کنید.

در ادامه، حداقل مراحل مورد نیاز برای استقرار یک برنامه کاربردی شرح داده شده است:

  1. یک شناسه گروه برنامه برای برنامه خود ایجاد کنید تا با MatterExtension ارتباط برقرار کند.
    1. وارد پورتال توسعه‌دهندگان اپل شوید.
    2. یک شناسه گروه برنامه اضافه کنید. برای مثال، می‌تواند به صورت group.com.company.commissioning قالب‌بندی شود.
  2. دستگاه آزمایشی خود را در حساب توسعه‌دهنده ثبت کنید .

  3. برای مخاطب هدف اپلیکیشن خود، یک پروفایل ایجاد کنید.

    1. یک شناسه بسته نرم‌افزاری برای برنامه خود انتخاب کنید. این شناسه باید منحصر به فرد و توصیفی باشد. برای مثال، می‌تواند به صورت زیر قالب‌بندی شود:com.company.HomeApiSample این شناسه در ادامه‌ی این بخش استفاده خواهد شد.
    2. شناسه برنامه خود را ثبت کنید . در صورت درخواست، قابلیت‌های App Attest و App Groups را اضافه کنید.

    3. شناسه برنامه تازه ایجاد شده را ویرایش کنید و قابلیت گروه‌های برنامه را برای افزودن شناسه گروه برنامه ثبت شده پیکربندی کنید.

    4. یک پروفایل تأمین توسعه برای توسعه برنامه خود ایجاد کنید . آن را به شناسه برنامه تازه ایجاد شده و دستگاه‌های آزمایشی انتخاب شده خود مرتبط کنید. مطمئن شوید که یک گواهی توسعه‌دهنده برای امضای برنامه دارید.

  4. برای هدف MatterExtension خود یک پروفایل ایجاد کنید.

    1. یک شناسه بسته نرم‌افزاری برای MatterExtension خود انتخاب کنید. این شناسه باید از شناسه برنامه به ارث برده شود. برای مثال، می‌تواند به صورت زیر قالب‌بندی شود: com.company.HomeApiSample.MatterExtension .
    2. شناسه برنامه خود را ثبت کنید . در صورت درخواست، قابلیت گروه برنامه را اضافه کنید.
    3. شناسه برنامه تازه ایجاد شده را ویرایش کنید و قابلیت گروه‌های برنامه را پیکربندی کنید تا شناسه گروه برنامه ثبت شده ایجاد شده در مراحل قبلی را اضافه کنید.
    4. یک پروفایل تأمین توسعه برای MatterExtension ایجاد کنید.

شناسه کلاینت OAuth را ایجاد کنید و APIهای Home را فعال کنید

برنامه شما برای شناسایی خود در بک‌اند احراز هویت گوگل به یک شناسه کلاینت OAuth نیاز دارد. برای iOS و برنامه‌ها، نوع برنامه شناسه کلاینت OAuth باید روی iOS پیکربندی شود. برنامه همچنین API Home را فراخوانی می‌کند. برای فعال کردن این قابلیت، API باید در پروژه Google Cloud فعال شود.

شناسه کلاینت OAuth را ایجاد کنید

  1. در کنسول گوگل کلود، به داشبورد انتخاب پروژه بروید و پروژه‌ای را که می‌خواهید برای ایجاد اعتبارنامه‌های OAuth از آن استفاده کنید، انتخاب کنید.
  2. با کلیک روی دکمه منو در سمت چپ بالا > مشاهده همه محصولات > APIها و خدمات، به صفحه APIها و خدمات بروید.
  3. در منوی پیمایش، روی اعتبارنامه‌ها کلیک کنید.

  4. اگر هنوز صفحه رضایت خود را برای این پروژه Google Cloud پیکربندی نکرده‌اید، دکمه پیکربندی صفحه رضایت ظاهر می‌شود. در این صورت، صفحه رضایت خود را با استفاده از روش زیر پیکربندی کنید. اگر صفحه رضایت OAuth شما قبلاً پیکربندی شده است و وضعیت انتشار آن در حالت Testing است، مطمئن شوید که حساب‌های آزمایشی که استفاده خواهید کرد به گروه کاربران آزمایشی اضافه شده‌اند. در غیر این صورت، به مرحله بعدی بروید.

    1. بسته به مورد استفاده شما، داخلی (Internal ) یا خارجی (External) را انتخاب کنید و سپس روی ایجاد (Create) کلیک کنید. صفحه رضایت OAuth نمایش داده می‌شود.
    2. طبق دستورالعمل‌های روی صفحه، اطلاعات را در صفحه اطلاعات برنامه وارد کنید و سپس روی ذخیره و ادامه کلیک کنید. پنجره Scopes نمایش داده می‌شود.
    3. نیازی به اضافه کردن هیچ محدوده‌ای ندارید، بنابراین روی ذخیره و ادامه کلیک کنید. پنجره‌ی کاربران آزمایشی نمایش داده می‌شود.
    4. اگر تصمیم به ایجاد صفحه رضایت داخلی گرفته‌اید، باید کاربرانی را برای آزمایش دسترسی به برنامه خود اضافه کنید. روی افزودن کاربران کلیک کنید. پنجره افزودن کاربران نمایش داده می‌شود. کاربران آزمایشی این امتیاز را دارند که در برنامه شما مجوز اعطا کنند. در فیلد خالی، یک یا چند آدرس ایمیل حساب گوگل اضافه کنید و سپس روی افزودن کلیک کنید.
    5. روی ذخیره و ادامه کلیک کنید. پنجره خلاصه نمایش داده می‌شود.
    6. اطلاعات صفحه رضایت OAuth خود را مرور کنید و سپس روی «بازگشت به داشبورد» کلیک کنید.

  5. در پنل منوی سمت چپ، روی Credentials کلیک کنید تا شناسه کلاینت OAuth خود را ایجاد کنید.

    تنظیم صفحه OAuth

    1. روی دکمه‌ی CREATE CREDENTIALS کلیک کنید و OAuth client ID را انتخاب کنید.
      1. در قسمت نوع برنامه ، iOS را انتخاب کنید.
    2. شناسه بسته (Bundle ID) را به همراه شناسه برنامه و شناسه تیم توسعه‌دهنده اپل خود وارد کنید. سایر فیلدها اختیاری هستند و می‌توانند خالی بمانند.
    3. روی CREATE کلیک کنید و Client ID یا DOWNLOAD PLIST ایجاد شده را یادداشت کنید. این بعداً برای فعال کردن قابلیت جریان مجوزها استفاده خواهد شد. برای اطلاعات بیشتر، به بخش ایجاد اعتبارنامه‌های مجوز مراجعه کنید.

فعال کردن APIهای صفحه اصلی

دسترسی به APIهای صفحه اصلی را فعال کنید.

  1. در برگه APIها و خدمات ، روی APIها و خدمات فعال‌شده کلیک کنید.
  2. روی گزینه فعال کردن APIS AND SERVICES در بالای صفحه کلیک کنید.
  3. HOME API را جستجو کرده و آن را انتخاب کنید.
  4. در صفحه جزئیات API صفحه اصلی ، روی فعال کردن (ENABLE) کلیک کنید.

کد منبع را دانلود کنید

کد منبع برنامه نمونه در GitHub موجود است.

به جایی که می‌خواهید پروژه را ذخیره کنید بروید، سپس آن را کلون کنید:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

برای بارگذاری پروژه در Xcode، روی File > Open کلیک کنید و GoogleHomeAPISampleIOS.xcodeproj در ریشه مخزن کلون شده انتخاب کنید.

SDK را تنظیم کنید

پروژه‌ی Sample App برای ساخت به اطلاعات بیشتری نیاز دارد. این اطلاعات شامل اضافه کردن فایل‌های SDK Framework به صورت محلی، پر کردن اطلاعات شناسه‌ی حساب توسعه‌دهنده و پر کردن شناسه‌ی کلاینت OAuth شما می‌شود.

ساخت اپلیکیشن

برای دانلود کیت توسعه نرم‌افزاری iOS برای رابط‌های برنامه‌نویسی کاربردی هوم (Home APIs)، ابتدا باید وارد حساب کاربری توسعه‌دهندگان گوگل هوم (Google Home Developers) شوید.

همین حالا وارد شوید!

پروژه Xcode خود را برای برنامه نمونه پیکربندی کنید:

  1. در پنل ناوبری Xcode، فایل GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.

    تنظیم برنامه نمونه SDK

  2. روی تب General در بالا کلیک کنید و GoogleHomeAPISampleIOS مورد نظر را در سمت چپ انتخاب کنید.

  3. به پایین اسکرول کنید تا بخش چارچوب‌ها، کتابخانه‌ها و محتوای جاسازی‌شده را ببینید. باید دو چارچوب API خانگی را در فهرست ببینید.

  4. در ستون Embed ، گزینه Embed & Sign را برای GoogleHomeSDK.xcframework انتخاب کنید. گزینه GoogleHomeTypes.xcframework باید روی Do Not Embed باقی بماند.

  5. در پایین لیست، روی آیکون + کلیک کنید.

  6. وقتی از شما خواسته شد، SafariServices.framework را جستجو کنید و روی افزودن کلیک کنید. مطمئن شوید که ستون Embed برای این ورودی روی Do Not Embed تنظیم شده است.

    جاسازی و امضا

  7. برای ویرایش هدف، روی MatterAddDeviceExtension در زیر Target کلیک کنید.

  8. به پایین اسکرول کنید تا بخش «چارچوب‌ها و کتابخانه‌ها» را ببینید. باید GoogleHomeSDK.xcframework در فهرست ببینید.

  9. در ستون «جاسازی» ، گزینه «جاسازی نشود» را انتخاب کنید.

  10. شناسه‌های توسعه‌دهنده و کلاینت OAuth را پیکربندی کنید:

    1. در پنل ناوبری، پوشه GoogleHomeAPISampleIOS را پیدا کنید و فایل Info.plist را برای ویرایش باز کنید.

  11. در فایل Info.plist ، مقدار GIDClientID را با شناسه کلاینت OAuth خود (به بخش تنظیم رضایت‌نامه OAuth مراجعه کنید)، شماره پروژه ابری مربوط به پروژه ابری خود و GIDTeamID را با شناسه تیم توسعه‌دهنده اپل حساب توسعه‌دهنده‌ای که در طول فرآیند ثبت نام OAuth استفاده شده است، پر کنید.

  12. قابلیت App Attest را اضافه کنید:

    1. در پنل ناوبری Xcode، فایل پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی برگه Signing and Capabilities در بالا کلیک کنید و GoogleHomeAPISampleIOS هدف را در سمت چپ، زیر بخش TARGETS انتخاب کنید.
    3. درست زیر تب Signing and Capabilities، روی + Capability کلیک کنید و App Attest را جستجو کنید.
    4. برای افزودن، روی App Attest کلیک کنید. اگر این قابلیت در جستجو وجود ندارد، ممکن است پروژه قبلاً آن را اضافه کرده باشد.

  13. قابلیت گروه‌های برنامه را اضافه کنید.

    اضافه کردن گروه‌های برنامه

    1. به پروژه GoogleHomeAPISampleIOS > هدف GoogleHomeAPISampleIOS بروید.
    2. روی امضا و قابلیت‌ها > + قابلیت کلیک کنید.
    3. قابلیت گروه‌های برنامه (App Groups) را انتخاب کنید.
    4. روی آیکون + در زیر گروه‌های برنامه کلیک کنید و شناسه گروه‌های برنامه را برای برنامه خود که در پورتال توسعه‌دهندگان اپل اضافه کرده‌اید، اضافه کنید.
    5. این مراحل را برای هدف MatterAddDeviceExtension تکرار کنید تا آن را به App Groups اضافه کنید.

  14. شناسه بسته نرم‌افزاری را به‌روزرسانی کنید

    1. برای اجرای موفقیت‌آمیز و استقرار برنامه نمونه روی سخت‌افزار با استفاده از گواهینامه‌های توسعه‌دهنده و پروفایل‌های تأمین، باید یک شناسه بسته منحصر به فرد ارائه دهید. این باید همان شناسه مرتبط با اعتبارنامه‌های کلاینت OAuth شما باشد (به بالا مراجعه کنید).
    2. در پنل ناوبری Xcode، فایل پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    3. روی برگه Signing and Capabilities در بالا کلیک کنید و GoogleHomeAPISampleIOS هدف را در سمت چپ، زیر بخش TARGETS انتخاب کنید.
    4. فیلد شناسه بسته (Bundle Identifier) ​​را در بخش امضا (Signing) انتخاب کنید و شناسه منحصر به فرد برنامه (Application) را وارد کنید.
    5. نمایه تأمین مربوط به آن بسته را با مجوزهای لازم انتخاب یا نصب کنید.
    6. این مراحل را برای هدف MatterAddDeviceExtension تکرار کنید تا شناسه Bundle را برای افزونه وارد کرده و نمایه تأمین ثبت شده آن را وارد کنید.

  15. شناسه گروه برنامه ثبت شده را در کد به‌روزرسانی کنید.

    1. برنامه باید نمونه SDK را طوری پیکربندی کند که از شناسه گروه برنامه برای ویژگی‌هایی مانند راه‌اندازی دستگاه استفاده کند. برنامه را به‌روزرسانی کنید تا از شناسه گروه برنامه ثبت‌شده در پورتال توسعه‌دهندگان اپل استفاده کند. برای این کار، رشته HOME_API_TODO_ADD_APP_GROUP را جستجو کنید و هر نمونه را با آن جایگزین کنید.

    این تنظیمات در فایل‌های زیر انجام می‌شوند:

    • GoogleHomeAPISampleIOS.swift هنگام مقداردهی اولیه SDK.
    • RequestHandler.swift
    • CommissioningManager.swift