ساختن برنامه نمونه iOS

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

پیش‌نیازها

مطمئن شوید که حداقل الزامات لازم برای استفاده از «میاناهای برنامه‌سازی کاربردی خانه» برای iOS را دارید.

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

بارگیری Xcode

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

  1. حساب Google.
  2. «شناسه Apple» در برنامه توسعه‌دهندگان Apple ثبت‌نام کرده باشد تا فایل‌های پیکربندی دستگاه فیزیکی تولید کند. اگر قبلاً ایجاد نشده باشد، ثبت‌نام هزینه اضافی دارد و ممکن است تکمیل آن تا ۴۸ ساعت طول بکشد.
  3. دستگاه iOS (نه شبیه‌ساز) با iOS نسخه ۱۶.۴ یا بالاتر که با حساب آزمایشی راه‌اندازی شده باشد.
  4. شبکه Wi-Fi.
  5. مرکز Google که از Home APIs پشتیبانی می‌کند.
  6. اگر دستگاهتان به Thread نیاز دارد و هاب شما این قابلیت را ندارد، به Thread Border Router (TBR) نیاز دارید.
  7. حداقل یک نوع دستگاه پشتیبانی‌شده.

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

  • macOS Sonoma یا جدیدتر
  • ‫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 و App Groups را اضافه کنید.

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

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

  4. برای MatterExtension هدف خود نمایه بسازید.

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

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

برنامه شما به شناسه کارخواه OAuth نیاز دارد تا خود را به پس‌زمینه اصالت‌سنجی Google معرفی کند. برای iOS و برنامه‌ها، نوع برنامه شناسه کارخواه OAuth باید به‌عنوان iOS پیکربندی شود. این برنامه همچنین به Home API فراخوانی خواهد کرد. برای فعال کردن این عملکرد، باید 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 Developer Team ID وارد کنید. فیلدهای دیگر اختیاری هستند و می‌توانند خالی بمانند.
    3. روی ایجاد کلیک کنید و شناسه مشتری ایجادشده یا بارگیری PLIST را یادداشت کنید. این مورد بعداً برای فعال کردن عملکرد جریان اجازه‌ها استفاده خواهد شد. برای اطلاعات بیشتر، بخش ایجاد اطلاعات اعتباری مجوز را ببینید.

فعال کردن 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 را در ریشه مخزن کلون‌شده انتخاب کنید.

افزودن کیت توسعه نرم‌افزار به پروژه

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

ساختن برنامه

برای بارگیری Home APIs iOS SDK، ابتدا باید به سیستم Google Home Developers وارد شوید.

اکنون به سیستم وارد شوید!

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

  1. کیت توسعه نرم‌افزار بارگیری‌شده را در دایرکتوری ThirdParty/GoogleHomeSDK نسبت‌به دایرکتوری ریشه پروژه از حالت فشرده خارج کنید.
  2. شناسه‌های توسعه‌دهنده و کارخواه OAuth را پیکربندی کنید:
    1. در قاب پیمایش، پوشه GoogleHomeAPISampleIOS را پیدا کنید و فایل Info.plist را برای ویرایش باز کنید.

  3. در فایل Info.plist، GIDClientID را با شناسه کاربر OAuth خودتان (بخش راه‌اندازی موافقت OAuth را ببینید)، شماره پروژه Cloud مربوط به پروژه Cloud خودتان، و GIDTeamID را با شناسه تیم توسعه‌دهنده Apple حساب توسعه‌دهنده استفاده‌شده درطول فرایند ثبت OAuth تکمیل کنید.

  4. افزودن قابلیت App Attest:

    1. در قاب پیمایش Xcode، GoogleHomeAPISampleIOS فایل پروژه را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی برگه Signing and Capabilities (امضا و قابلیت‌ها) در بالا کلیک کنید و هدف GoogleHomeAPISampleIOS را در سمت راست زیر بخش TARGETS (اهداف) انتخاب کنید.
    3. درست زیر برگه «امضا و قابلیت‌ها»، روی + قابلیت کلیک کنید و 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. فیلد «شناسه دسته نرم‌افزاری» را در بخش امضا انتخاب کنید و شناسه یکتای «برنامه» را وارد کنید.
    5. نمایه تدارک مربوط به آن بسته را با حقوق لازم انتخاب یا نصب کنید.
    6. این مراحل را برای هدف MatterAddDeviceExtension تکرار کنید تا شناسه دسته نرم‌افزاری را برای افزونه وارد کنید و نمایه تدارک ثبت‌شده آن را وارد کنید.

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

    1. برنامه باید نمونه کیت توسعه نرم‌افزار را پیکربندی کند تا بتواند از شناسه «گروه برنامه» برای ویژگی‌هایی مثل راه‌اندازی دستگاه استفاده کند. برنامه را به‌روز کنید تا از «شناسه گروه برنامه» ثبت‌شده در «درگاه توسعه‌دهندگان Apple» استفاده کند. برای این کار، رشته 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
  ...
}