برنامه نمونه Home APIs Android

«برنامه نمونه» قابلیت‌های پایه Google Home API برای Android را نمایش می‌دهد.

پیش‌نیازها

برای ساختن، نصب کردن، و آزمایش کردن برنامه، باید چند پیش‌نیاز را برآورده کنید:

  • Android Studio، نسخه 2024.2.1 («Ladybug») یا جدیدتر. توجه داشته باشید که نسخه‌های قدیمی‌تر از این ممکن است با کیت توسعه نرم‌افزار Home APIs به‌درستی کار نکنند.

    بارگیری «استودیو Android»

  • اشکال‌زدای Android‏ (adb).

    adb را نصب کنید.

    این کار را می‌توان با مدیر SDK انجام داد.

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

  • دستگاه Android با Android نسخه ۱۰ یا بالاتر که با «حساب Google» راه‌اندازی شده باشد و قصد داشته باشید از آن برای توسعه استفاده کنید. مطمئن شوید نسخه به‌روز Android Studio نصب شده باشد و با این حساب توسعه به سیستم وارد شده باشید.
  • شبکه Wi-Fi.
  • برای دسترسی و کنترل دستگاه‌های Matter، به هاب Google که از Home API پشتیبانی می‌کند نیز نیاز دارید. برای جزئیات، اتصال‌پذیری در Android را ببینید.

  • حداقل یک دستگاه پشتیبانی‌شده در خانه. اگر این دستگاه (یا هر دستگاه دیگری که می‌خواهید آزمایش کنید) از Thread استفاده می‌کند، هاب نیز باید Thread Border Router (TBR) باشد. انواع و ویژگی‌های دستگاه زیر توسط «برنامه نمونه Android» پشتیبانی می‌شود:

    • چراغ دمای رنگ (روشن و خاموش، روشنایی)
    • حسگر تماسی (وضعیت بولی)
    • چراغ با نور قابل‌تنظیم (روشن و خاموش، روشنایی)
    • قفل در
    • Extended Color Light (روشن و خاموش، روشنایی)
    • کلید عمومی
    • رهیاب مرزی Google
    • دوربین Google
    • Google Doorbell
    • حسگر حضور در خانه (تشخیص حضور در خانه)
    • روشن/خاموش کردن چراغ (روشن و خاموش، روشنایی)
    • کلید روشن/خاموش چراغ
    • واحد افزایه روشن/خاموش (روشن و خاموش)
    • حسگر روشن/خاموش

بارگیری کد منبع

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

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

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

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

میاناهای برنامه‌سازی کاربردی Home برای Android در این نسخه بتای باز هنوز بخشی از کتابخانه‌های استانداردی نیستند که Google برای توسعه ارائه می‌دهد. برای توسعه برنامه‌های Android با Home API، باید کتابخانه‌ها را به‌صورت محلی بارگیری و میزبانی کنید.

برای بارگیری کیت توسعه نرم‌افزار Android برای Home API، ابتدا باید به سیستم Google Home Developers وارد شوید.

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

ساختن برنامه

  1. Android Studio را باز کنید، سپس پوشه پروژه google-home-api-sample-app-android را که در دستگاه محلی‌تان کلون شده است باز کنید.

  2. درطول اولین راه‌اندازی، ممکن است تا ۱۰ دقیقه طول بکشد تا Android Studio همه وابستگی‌های پروژه را بارگیری کند و ساخت Gradle را تکمیل کند.

  3. رایانه‌تان را ازطریق کابل USB به تلفن Android فیزیکی متصل کنید و ADB را در گزینه‌های توسعه‌دهنده فعال کنید. مطمئن شوید Android Studio بتواند ازطریق ADB به تلفن Android متصل شود.

  4. نام بسته «برنامه نمونه» را به نام جدیدی که قبلاً ثبت نشده است تغییر دهید، مثلاً نامی براساس نام سازمانتان:

    1. پروژه را باز کنید.
    2. سلسله‌مراتب منبع را ازهم باز کنید.
    3. بخشی از بسته را که می‌خواهید تغییر دهید انتخاب کنید - به عبارت دیگر، com.example.
    4. روی بسته کلیک راست کنید و بازسازی کد > تغییر نام... را انتخاب کنید منو «بازسازی کد > تغییر نام»
    5. نام جدید را وارد کنید و روی بازسازی کد کلیک کنید.
    6. فایل build.gradle.kts را ویرایش کنید و android namespace و applicationId را به نام بسته جدید تغییر دهید.

  5. گستره OAuth را در HomeModule.kt پیکربندی کنید. به‌طور پیش‌فرض، کد منبع «برنامه نمونه» از گستره https://www.googleapis.com/auth/home.platform.v2 استفاده می‌کند. بسیاری از ویژگی‌های «برنامه نمونه» با گستره home.platform.v2 محدود شده‌اند و برای دسترسی به آن‌ها به تأیید شریک نیاز است. برای اجرای «برنامه نمونه» با گستره استاندارد https://www.googleapis.com/auth/home.platform.selected.devices، HomeModule.kt را باز کنید و homePlatformScope را در HomeConfig به HOME_PLATFORM_SCOPE_VERSION_1 تغییر دهید:

    val homeConfig = HomeConfig(
  coroutineContext = Dispatchers.IO,
  factoryRegistryProvider = {
    FactoryConstants.factoryRegistryAllTraitsAllTypes
  },
  homePlatformScope =
    HomeConfig.HomePlatformScope.HOME_PLATFORM_SCOPE_VERSION_1
)

همچنین homePlatformScope را به HOME_PLATFORM_SCOPE_VERSION_1 در switchAccount() در HomeClientProvider.kt به‌روز کنید. درغیراین‌صورت، انتخاب کردن نماد نمایه برای عوض کردن حساب، برنامه را به HOME_PLATFORM_SCOPE_VERSION_2 برمی‌گرداند.

  1. پس‌از بارگیری همه کتابخانه‌های لازم و تکمیل همگام‌سازی Gradle، روی دکمه اجرا کلیک کنید تا برنامه ساخته و اجرا شود. وقتی برنامه با موفقیت در تلفنتان اجرا شد، صفحه اصلی «برنامه نمونه» را خواهید دید.

ایجاد گواهی امضا

وقتی برنامه‌ای را در Android Studio اجرا یا اشکال‌زدایی می‌کنید، به‌طور خودکار گواهینامه اشکال‌زدایی‌ای تولید می‌کند که برای توسعه و اشکال‌زدایی درنظر گرفته شده است. برای توضیحات کامل، Android Studio: Sign your debug build را ببینید.

  1. با اجرای برنامه در Android Studio، گواهی امضای برنامه اشکال‌زدایی تولید کنید. وقتی برنامه‌ای را در Android Studio اجرا یا اشکال‌زدایی می‌کنید، Android Studio به‌طور خودکار گواهی امضای برنامه را برای توسعه و اشکال‌زدایی تولید می‌کند. برای توضیحات کامل، Android Studio: Sign your debug build (استودیو Android: امضای ساخت اشکال‌زدایی) را ببینید.

    دستگاه همراهتان را به دستگاه محلی‌تان متصل کنید. Android Studio دستگاه‌های متصل‌شده را براساس شماره مدل فهرست می‌کند. دستگاهتان را از فهرست انتخاب کنید، سپس روی اجرای پروژه کلیک کنید. این کار «برنامه نمونه» را در دستگاه همراهتان می‌سازد و نصب می‌کند.

    برای دستورالعمل‌های دقیق‌تر، به اجرای برنامه‌ها در دستگاه سخت‌افزاری در سایت «توسعه‌دهندگان Android» مراجعه کنید.

    اکنون برنامه درحال اجرا را متوقف کنید.

  2. با دنبال کردن دستورالعمل‌های شرح‌داده‌شده در مدیریت کارخواه‌های OAuth / انواع برنامه / برنامه‌های بومی / Android در سایت «راهنمای Google Cloud Console»، اثر انگشت SHA-1 گواهینامه اشکال‌زدایی‌تان را دریافت کنید.

  1. در کنسول Google Cloud، به داشبورد انتخابگر پروژه بروید و پروژه‌ای را که می‌خواهید برای ایجاد اطلاعات کاربری OAuth استفاده کنید انتخاب کنید.
  2. به صفحه میاناهای برنامه‌سازی کاربردی و سرویس‌ها بروید و در منو پیمایش روی اطلاعات کاربری کلیک کنید.

  3. اگر هنوز صفحه رضایت را برای این پروژه Google Cloud پیکربندی نکرده‌اید، دکمه پیکربندی صفحه رضایت نشان داده می‌شود. در این صورت، صفحه رضایتتان را بااستفاده از روال زیر پیکربندی کنید. درغیراین‌صورت، به بخش بعدی بروید.

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

برای جزئیات کامل، به راه‌اندازی صفحه رضایت OAuth در سایت راهنمای «کنسول Google Cloud» مراجعه کنید. حتماً قبل‌از ادامه دادن، حداقل یک کاربر آزمایشی اضافه کنید.

راه‌اندازی اعتبارنامه‌های OAuth

  1. «برنامه نمونه» را برای OAuth 2.0 ثبت کنید و با دنبال کردن دستورالعمل‌های ارائه‌شده در راه‌اندازی OAuth 2.0، اعتبارنامه‌های OAuth را ایجاد کنید.
    1. نوع برنامه را که برنامه بومی/Android است مشخص کنید.
    2. با دنبال کردن دستورالعمل‌های راه‌اندازی OAuth 2.0 / برنامه‌های بومی / Android در سایت راهنمای Google Cloud Console، اثر انگشت SHA-1 را به کارخواه OAuth اضافه کنید. باید کلید SHA-1 را از کلید پیش‌فرض Android Studio درطول فرایند توسعه تولید کنید.

اجرای برنامه

  1. درحالی‌که دستگاه همراهتان به دستگاه محلی متصل است، دوباره روی اجرای پروژه کلیک کنید تا «برنامه نمونه» در دستگاه همراهتان اجرا شود.

پس‌از نصب، برنامه در دستگاه همراهتان با نام Home API Sample App دردسترس خواهد بود.