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

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

پیش‌نیازها

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

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

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

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

    نصب adb.

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

و برای آزمایش «میاناهای برنامه‌سازی کاربردی خانه هوشمند»، به موارد زیر نیاز دارید:

  • دستگاه 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 با «میاناهای برنامه‌سازی کاربردی خانه»، باید کتابخانه‌ها را به‌صورت محلی بارگیری و میزبانی کنید.

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

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

ساختن برنامه

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

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

  3. رایانه خود را ازطریق کابل USB به تلفن Android فیزیکی وصل کنید و «پل اشکال‌زدایی Android» را در گزینه‌های توسعه‌دهنده فعال کنید. مطمئن شوید 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 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 دردسترس است.