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

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

پیش‌نیازها

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

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

بارگیری Xcode

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

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

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

  • macOS Sonoma یا نسخه‌های جدیدتر
  • ‫Xcode نسخه ۱۵.۳ یا بالاتر

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

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

دوم، برای ارتباط بین برنامه و 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 را فعال کنید

برنامه شما برای شناساندن خود به زیرینه درستی‌سنجی Google به شناسه کارخواه OAuth نیاز دارد. برای 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. افزودن قابلیت «گواهی برنامه»:

    1. در قاب پیمایش Xcode، GoogleHomeAPISampleIOS فایل پروژه را برای ویرایش پیکربندی پروژه انتخاب کنید.
    2. روی برگه امضا و قابلیت‌ها در بالا کلیک کنید و هدف GoogleHomeAPISampleIOS را در سمت راست زیر بخش «هدف‌ها» انتخاب کنید.
    3. درست زیر برگه «امضا و قابلیت‌ها»، روی + قابلیت کلیک کنید و App Attest را جستجو کنید.
    4. برای افزودن، روی App Attest کلیک کنید. اگر این قابلیت در جستجو وجود ندارد، ممکن است پروژه ازقبل آن را اضافه کرده باشد.

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

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

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

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

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

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

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

    این پیکربندی‌ها در فایل‌های زیر انجام می‌شود:

    • وقتی «کیت توسعه نرم‌افزار» مقداردهی اولیه می‌شود، GoogleHomeAPISampleIOS.swift.
    • RequestHandler.swift
    • CommissioningManager.swift