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

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

پیش نیازها

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

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

Xcode را دانلود کنید

برای تست برنامه، شما نیاز دارید:

  1. یک حساب Google که در Home APIs EAP ثبت شده و به عنوان یک حساب آزمایشی خدمت می کند.
  2. یک شناسه Apple ثبت‌شده در برنامه توسعه‌دهنده اپل برای تولید فایل‌های پیکربندی دستگاه فیزیکی. اگر قبلاً ایجاد نشده باشد، ثبت نام مستلزم هزینه اضافی است و ممکن است تکمیل آن تا 48 ساعت طول بکشد.
  3. یک دستگاه iOS (نه شبیه ساز) دارای iOS 16.4+ که با حساب آزمایشی راه اندازی شده است.
  4. یک شبکه وای فای
  5. یک مرکز Google که از APIهای Home پشتیبانی می کند .
  6. اگر دستگاه شما به Thread نیاز دارد و هاب شما این قابلیت را ندارد، روتر مرزی Thread.
  7. حداقل یک نوع دستگاه پشتیبانی شده

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

  • macOS Sonoma یا جدیدتر
  • Xcode 15.3 یا بالاتر

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

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

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

برای جزئیات بیشتر، Apple's Create a developing provisioning profile on provisioning profiles را ببینید.

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

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

  3. یک نمایه برای هدف برنامه خود ایجاد کنید.

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

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

    4. یک نمایه تهیه برنامه برای توسعه برنامه خود ایجاد کنید . آن را به App ID جدید ایجاد شده و دستگاه های آزمایشی انتخاب شده مرتبط کنید. اطمینان حاصل کنید که یک گواهی توسعه دهنده برای امضای برنامه دارید.

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

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

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

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

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

  1. در کنسول Google Cloud، به داشبورد انتخابگر پروژه بروید و پروژه ای را که می خواهید برای ایجاد اعتبار OAuth استفاده کنید، انتخاب کنید.
  2. با کلیک بر روی دکمه منو در سمت چپ بالا > مشاهده همه محصولات > APIs & Services به صفحه APIs and Services بروید.
  3. در منوی پیمایش، روی اعتبارنامه کلیک کنید.

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

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

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

    صفحه OAuth را تنظیم کنید

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

API های Home را فعال کنید

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

  1. در برگه APIs and Services ، روی Enabled APIs & Services کلیک کنید.
  2. روی ENABLE APIS AND SERVICES در بالای صفحه کلیک کنید.
  3. HOME API را جستجو کرده و آن را انتخاب کنید.
  4. در صفحه جزئیات Home API ، روی ENABLE کلیک کنید.

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

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

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

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

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

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

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

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

برای دانلود Home APIs iOS SDK، ابتدا باید وارد Google Home Developers شوید.

اکنون وارد شوید!

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

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

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

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

  3. به پایین بروید تا قسمت Frameworks، Libraries و Embedded Content را ببینید. شما باید دو چارچوب API Home را در لیست مشاهده کنید.

  4. در ستون Embed ، Embed & Sign for GoogleHomeSDK.xcframework را انتخاب کنید. چارچوب دیگر، GoogleHomeTypes.xcframework ، باید به عنوان جاسازی نشود باقی بماند.

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

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

    جاسازی و امضا کنید

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

  8. به پایین بروید تا قسمت Frameworks and Libraries را ببینید. باید فهرست GoogleHomeSDK.xcframework را ببینید.

  9. در ستون Embed ، جاسازی نشود را انتخاب کنید.

  10. شناسه های سرویس گیرنده Developer و OAuth را پیکربندی کنید:

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

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

  12. پیکربندی سیستم ساخت:

    پرچم های پیوند دهنده را اضافه کنید

    1. در صفحه پیمایش Xcode، فایل پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی تب Build Settings در بالا کلیک کنید و GoogleHomeAPISampleIOS مورد نظر را در سمت چپ در قسمت TARGETS انتخاب کنید.
    3. سایر پرچم های پیوند دهنده را جستجو کنید و دو ورودی اضافه کنید:
      • -lc++
      • -ObjC

  13. افزودن قابلیت App Atest:

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

  14. قابلیت App Groups را اضافه کنید.

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

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

  15. شناسه Bundle را به روز کنید

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

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

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

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

    • GoogleHomeAPISampleIOS.swift هنگامی که SDK اولیه می شود.
    • RequestHandler.swift
    • CommissioningManager.swift
،

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

پیش نیازها

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

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

Xcode را دانلود کنید

برای تست برنامه، شما نیاز دارید:

  1. یک حساب Google که در Home APIs EAP ثبت شده و به عنوان یک حساب آزمایشی خدمت می کند.
  2. یک شناسه Apple ثبت‌شده در برنامه توسعه‌دهنده اپل برای تولید فایل‌های پیکربندی دستگاه فیزیکی. اگر قبلاً ایجاد نشده باشد، ثبت نام مستلزم هزینه اضافی است و ممکن است تکمیل آن تا 48 ساعت طول بکشد.
  3. یک دستگاه iOS (نه شبیه ساز) دارای iOS 16.4+ که با حساب آزمایشی راه اندازی شده است.
  4. یک شبکه وای فای
  5. یک مرکز Google که از APIهای Home پشتیبانی می کند .
  6. اگر دستگاه شما به Thread نیاز دارد و هاب شما این قابلیت را ندارد، روتر مرزی Thread.
  7. حداقل یک نوع دستگاه پشتیبانی شده

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

  • macOS Sonoma یا جدیدتر
  • Xcode 15.3 یا بالاتر

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

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

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

برای جزئیات بیشتر، Apple's Create a developing provisioning profile on provisioning profiles را ببینید.

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

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

  3. یک نمایه برای هدف برنامه خود ایجاد کنید.

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

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

    4. یک نمایه تهیه برنامه برای توسعه برنامه خود ایجاد کنید . آن را به App ID جدید ایجاد شده و دستگاه های آزمایشی انتخاب شده مرتبط کنید. اطمینان حاصل کنید که یک گواهی توسعه دهنده برای امضای برنامه دارید.

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

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

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

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

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

  1. در کنسول Google Cloud، به داشبورد انتخابگر پروژه بروید و پروژه ای را که می خواهید برای ایجاد اعتبار OAuth استفاده کنید، انتخاب کنید.
  2. با کلیک بر روی دکمه منو در سمت چپ بالا > مشاهده همه محصولات > APIs & Services به صفحه APIs and Services بروید.
  3. در منوی پیمایش، روی اعتبارنامه کلیک کنید.

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

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

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

    صفحه OAuth را تنظیم کنید

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

API های Home را فعال کنید

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

  1. در برگه APIs and Services ، روی Enabled APIs & Services کلیک کنید.
  2. روی ENABLE APIS AND SERVICES در بالای صفحه کلیک کنید.
  3. HOME API را جستجو کرده و آن را انتخاب کنید.
  4. در صفحه جزئیات Home API ، روی ENABLE کلیک کنید.

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

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

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

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

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

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

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

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

برای دانلود Home APIs iOS SDK، ابتدا باید وارد Google Home Developers شوید.

اکنون وارد شوید!

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

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

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

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

  3. به پایین بروید تا قسمت Frameworks، Libraries و Embedded Content را ببینید. شما باید دو چارچوب API Home را در لیست مشاهده کنید.

  4. در ستون Embed ، Embed & Sign for GoogleHomeSDK.xcframework را انتخاب کنید. چارچوب دیگر، GoogleHomeTypes.xcframework ، باید به عنوان جاسازی نشود باقی بماند.

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

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

    جاسازی و امضا کنید

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

  8. به پایین بروید تا قسمت Frameworks and Libraries را ببینید. باید فهرست GoogleHomeSDK.xcframework را ببینید.

  9. در ستون Embed ، جاسازی نشود را انتخاب کنید.

  10. شناسه های سرویس گیرنده Developer و OAuth را پیکربندی کنید:

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

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

  12. پیکربندی سیستم ساخت:

    پرچم های پیوند دهنده را اضافه کنید

    1. در صفحه پیمایش Xcode، فایل پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی تب Build Settings در بالا کلیک کنید و GoogleHomeAPISampleIOS مورد نظر را در سمت چپ در قسمت TARGETS انتخاب کنید.
    3. سایر پرچم های پیوند دهنده را جستجو کنید و دو ورودی اضافه کنید:
      • -lc++
      • -ObjC

  13. افزودن قابلیت App Atest:

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

  14. قابلیت App Groups را اضافه کنید.

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

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

  15. شناسه Bundle را به روز کنید

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

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

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

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

    • GoogleHomeAPISampleIOS.swift هنگامی که SDK اولیه می شود.
    • RequestHandler.swift
    • CommissioningManager.swift
،

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

پیش نیازها

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

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

Xcode را دانلود کنید

برای تست برنامه، شما نیاز دارید:

  1. یک حساب Google که در Home APIs EAP ثبت شده و به عنوان یک حساب آزمایشی خدمت می کند.
  2. یک شناسه Apple ثبت‌شده در برنامه توسعه‌دهنده اپل برای تولید فایل‌های پیکربندی دستگاه فیزیکی. اگر قبلاً ایجاد نشده باشد، ثبت نام مستلزم هزینه اضافی است و ممکن است تکمیل آن تا 48 ساعت طول بکشد.
  3. یک دستگاه iOS (نه شبیه ساز) دارای iOS 16.4+ که با حساب آزمایشی راه اندازی شده است.
  4. یک شبکه وای فای
  5. یک مرکز Google که از APIهای Home پشتیبانی می کند .
  6. اگر دستگاه شما به Thread نیاز دارد و هاب شما این قابلیت را ندارد، روتر مرزی Thread.
  7. حداقل یک نوع دستگاه پشتیبانی شده

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

  • macOS Sonoma یا جدیدتر
  • Xcode 15.3 یا بالاتر

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

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

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

برای جزئیات بیشتر، Apple's Create a developing provisioning profile on provisioning profiles را ببینید.

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

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

  3. یک نمایه برای هدف برنامه خود ایجاد کنید.

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

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

    4. یک نمایه تهیه برنامه برای توسعه برنامه خود ایجاد کنید . آن را به App ID جدید ایجاد شده و دستگاه های آزمایشی انتخاب شده مرتبط کنید. اطمینان حاصل کنید که یک گواهی توسعه دهنده برای امضای برنامه دارید.

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

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

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

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

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

  1. در کنسول Google Cloud، به داشبورد انتخابگر پروژه بروید و پروژه ای را که می خواهید برای ایجاد اعتبار OAuth استفاده کنید، انتخاب کنید.
  2. با کلیک بر روی دکمه منو در سمت چپ بالا > مشاهده همه محصولات > APIs & Services به صفحه APIs and Services بروید.
  3. در منوی پیمایش، روی اعتبارنامه کلیک کنید.

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

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

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

    صفحه OAuth را تنظیم کنید

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

API های Home را فعال کنید

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

  1. در برگه APIs and Services ، روی Enabled APIs & Services کلیک کنید.
  2. روی ENABLE APIS AND SERVICES در بالای صفحه کلیک کنید.
  3. HOME API را جستجو کرده و آن را انتخاب کنید.
  4. در صفحه جزئیات Home API ، روی ENABLE کلیک کنید.

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

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

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

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

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

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

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

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

برای بارگیری Home APIS iOS SDK ، ابتدا باید به توسعه دهندگان Google Home امضا شوید.

اکنون وارد شوید!

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

  1. در صفحه Navigation XCode ، پرونده GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.

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

  2. روی برگه عمومی در بالا کلیک کنید و هدف GoogleHomeAPISampleIOS را در سمت چپ انتخاب کنید.

  3. به پایین بروید تا زمانی که چارچوب ها ، کتابخانه ها و بخش محتوای تعبیه شده را مشاهده کنید. شما باید دو چارچوب API خانگی را ذکر کنید.

  4. در ستون Embed ، Embed & Sign را برای GoogleHomeSDK.xcframework انتخاب کنید. چارچوب دیگر ، GoogleHomeTypes.xcframework ، باید همانطور که تعبیه نشده است باقی بماند.

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

  6. در صورت درخواست ، SafariServices.framework را جستجو کنید و روی افزودن کلیک کنید. اطمینان حاصل کنید که ستون تعبیه شده برای این مطلب جاسازی نشده است.

    تعبیه و امضا

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

  8. تا زمانی که بخش چارچوب ها و کتابخانه ها را مشاهده کنید ، به پایین بروید. شما باید GoogleHomeSDK.xcframework را ذکر کنید.

  9. در ستون Embed ، Select Not Embed را انتخاب کنید.

  10. شناسه مشتری توسعه دهنده و OAUTH را پیکربندی کنید:

    1. در صفحه ناوبری ، به دنبال پوشه GoogleHomeApisampleios باشید و پرونده info.plist را برای ویرایش باز کنید.

  11. در پرونده info.plist ، gidclientid را با شناسه مشتری OAUTH خود جمع کنید (به بخش رضایت OAUTH SET UT ) و GIDTEAMID با شناسه تیم توسعه دهنده اپل از حساب توسعه دهنده استفاده شده در فرآیند ثبت نام OAUTH استفاده کنید.

  12. سیستم ساخت را پیکربندی کنید:

    پرچم های پیوند دهنده را اضافه کنید

    1. در صفحه Navigation XCode ، پرونده پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی برگه Build Settings در قسمت بالا کلیک کنید و هدف GoogleHomeAPISampleIOS در سمت چپ در زیر بخش Targets انتخاب کنید.
    3. برای سایر پرچم های پیوند دهنده جستجو کنید و دو مدخل اضافه کنید:
      • -lc++
      • -ObjC

  13. اضافه کردن برنامه شهادت:

    1. در صفحه Navigation XCode ، پرونده پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی برگه امضای و قابلیت ها در بالا کلیک کنید و هدف GoogleHomeAPISampleIOS در سمت چپ در زیر بخش Targets انتخاب کنید.
    3. درست در زیر برگه امضای و قابلیت ها ، روی + قابلیت کلیک کرده و برای شهادت برنامه جستجو کنید.
    4. روی برنامه تأیید کنید تا اضافه کنید. اگر این قابلیت در جستجو وجود ندارد ، ممکن است این پروژه قبلاً آن را اضافه کرده باشد.

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

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

    1. به پروژه GoogleHomeApisampleios > GoogleHomeApisampleIos Target بروید.
    2. روی امضای و قابلیت ها کلیک کنید> + قابلیت .
    3. قابلیت گروه های برنامه را انتخاب کنید.
    4. روی نماد + زیر گروه های برنامه کلیک کنید و شناسه برنامه های برنامه را برای برنامه خود که در پورتال توسعه دهنده Apple اضافه کرده اید اضافه کنید.
    5. این مراحل را برای هدف MatterAddDeviceExtension تکرار کنید تا آن را به گروه های برنامه اضافه کنید.

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

    1. برای اجرای موفقیت آمیز و استقرار برنامه نمونه بر روی سخت افزار با استفاده از گواهینامه های توسعه دهنده خود و پروفایل های تهیه ، باید یک شناسه بسته نرم افزاری منحصر به فرد ارائه دهید. این باید همان شناسه مرتبط با اعتبار مشتری OAuth شما باشد (به بالا مراجعه کنید).
    2. در صفحه Navigation XCode ، پرونده پروژه GoogleHomeAPISampleIOS را برای ویرایش پیکربندی پروژه انتخاب کنید.
    3. روی برگه امضای و قابلیت ها در بالا کلیک کنید و هدف GoogleHomeAPISampleIOS در سمت چپ در زیر بخش Targets انتخاب کنید.
    4. قسمت شناسه Bundle را در بخش امضا انتخاب کنید و شناسه منحصر به فرد را برای برنامه وارد کنید.
    5. مشخصات ارائه دهنده مربوط به آن بسته نرم افزاری را با حق الزامات مورد نیاز انتخاب یا نصب کنید.
    6. این مراحل را برای هدف MatterAddDeviceExtension تکرار کنید تا شناسه بسته نرم افزاری را برای پسوند وارد کرده و نمایه تهیه ثبت شده خود را وارد کنید.

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

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

    این تنظیمات در پرونده های زیر ساخته شده است:

    • GoogleHomeAPISampleIOS.swift هنگام اولیه سازی SDK.
    • RequestHandler.swift
    • CommissioningManager.swift