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

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

پیش‌نیازها

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

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

بارگیری Xcode

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

  1. حساب Google.
  2. یک Apple ID ثبت‌شده در Apple Developer Program برای تولید فایل‌های پیکربندی دستگاه فیزیکی. اگر قبلاً ایجاد نشده باشد، ثبت‌نام هزینه اضافی دارد و ممکن است تا ۴۸ ساعت طول بکشد تا تکمیل شود.
  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 API

برنامه شما به شناسه کارخواه 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 وارد کنید. فیلدهای دیگر اختیاری هستند و می‌توانند خالی بمانند.
    3. روی ایجاد کلیک کنید و شناسه مشتری ایجادشده را یادداشت کنید یا روی بارگیری PLIST کلیک کنید. This will be used later to enable permissions flow functionality. برای اطلاعات بیشتر، بخش ایجاد اطلاعات اعتباری مجوز را ببینید.

فعال کردن Home APIs

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

  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 مراجعه کنید)، شماره پروژه ابری مربوط به پروژه ابری خود، و 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
  ...
}