Home APIs Android Sample App

באפליקציית הדוגמה מוצגות היכולות הבסיסיות של ממשקי Google Home API ל-Android.

דרישות מוקדמות

כדי ליצור, להתקין ולבדוק את האפליקציה, צריך לעמוד בכמה דרישות מוקדמות:

  • ‫Android Studio, גרסה 2024.2.1 (Ladybug) ואילך. שימו לב: יכול להיות שגרסאות קודמות לא יפעלו כמו שצריך עם Home APIs SDK.

    הורדת Android Studio

  • כלי לניפוי באגים ב-Android ‏ (adb).

    התקנה adb.

    אפשר לעשות את זה באמצעות SDK Manager.

כדי לבדוק את ממשקי ה-API של Home, תצטרכו:

  • מכשיר Android עם Android מגרסה 10 ואילך, שהוגדר בו חשבון Google שבו אתם רוצים להשתמש לפיתוח. מוודאים שמותקנת גרסה עדכנית של Android Studio ושנכנסתם אליה באמצעות חשבון הפיתוח הזה.
  • רשת Wi-Fi.
  • כדי לגשת למכשירי Matter ולשלוט בהם, צריך גם רכזת Google שתומכת בממשקי Home API. פרטים נוספים זמינים במאמר בנושא קישוריות ב-Android .

  • לפחות מכשיר אחד נתמך בבית. אם המכשיר הזה (או כל מכשיר אחר שרוצים לבדוק) משתמש בפרוטוקול Thread, הרכזת צריכה להיות גם נתב גבולות לפרוטוקול Thread. אפליקציית הדוגמה ל-Android תומכת בסוגי המכשירים וב-traits הבאים:

    • תאורה עם טמפרטורת צבע (הפעלה וכיבוי, בהירות)
    • חיישן מגע (מצב בוליאני)
    • תאורה ניתנת לעמעום (הפעלה וכיבוי, בהירות)
    • תאורה עם טווח צבעים רחב (הפעלה והשבתה, בהירות)
    • Generic Switch
    • חיישן נוכחות (גלאי נוכחות)
    • הפעלה/השבתה של התאורה (הפעלה והשבתה, בהירות)
    • מתג הפעלה/כיבוי של אור
    • יחידת פלאגין להפעלה/השבתה (הפעלה והשבתה)
    • חיישן הפעלה/כיבוי

הורדת קוד המקור

קוד המקור של האפליקציה לדוגמה זמין ב-GitHub.

מנווטים למקום שבו רוצים לשמור את הפרויקט, ואז משכפלים אותו:

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

הגדרת ה-SDK

ממשקי Home API ל-Android בגרסת הבטא הפתוחה הזו עדיין לא נכללים בספריות הרגילות ש-Google מספקת לפיתוח. כדי לפתח אפליקציות ל-Android באמצעות ממשקי ה-API של Home, צריך להוריד את הספריות ולשמור אותן באופן מקומי.

כדי להוריד את Android SDK של Home APIs, קודם צריך להיכנס אל Google Home Developers.

כניסה לחשבון

יצירת האפליקציה

  1. פותחים את Android Studio ואז פותחים את תיקיית הפרויקט google-home-api-sample-app-android ששוכפלה למחשב המקומי.

  2. במהלך ההגדרה הראשונית, יכול להיות שיידרשו עד 10 דקות להורדת כל יחסי התלות של הפרויקט ולהשלמת ה-build של Gradle ב-Android Studio.

  3. מחברים את המחשב לטלפון Android פיזי באמצעות כבל USB ומפעילים את ADB באפשרויות למפתחים. מוודאים שAndroid Studio יכול להתחבר לטלפון Android באמצעות ADB.

  4. משנים את שם החבילה של אפליקציית הדוגמה לשם חדש שלא נרשם בעבר, למשל שם שמבוסס על שם הארגון:

    1. פותחים את הפרויקט.
    2. מרחיבים את היררכיית המקורות.
    3. בוחרים את החלק בחבילה שרוצים לשנות – במילים אחרות, את com.example.
    4. לוחצים לחיצה ימנית על החבילה ובוחרים באפשרות Refactor (ארגון מחדש) > Rename... (שינוי שם...) שינוי מבנה קוד > שינוי שם התפריט
    5. מזינים את השם החדש ולוחצים על Refactor (שינוי מבנה הקוד).
    6. עורכים את הקובץ build.gradle.kts, משנים את android namespace ואת applicationId לשם החבילה החדש.

  5. אחרי שכל הספריות הנדרשות יורדו והסנכרון של Gradle יסתיים, לוחצים על הלחצן Run כדי ליצור את האפליקציה ולהפעיל אותה. כשהאפליקציה תפעל בהצלחה בטלפון, יוצג הדף הראשי של האפליקציה לדוגמה.

יצירת אישור חתימה

כשמריצים או מנפים באגים באפליקציה ב-Android Studio, המערכת יוצרת באופן אוטומטי אישור ניפוי באגים שמיועד לפיתוח ולניפוי באגים. הסבר מלא מופיע במאמר בנושא Android Studio: חתימה על גרסת ה-build לניפוי באגים.

  1. מריצים את האפליקציה ב-Android Studio כדי ליצור אישור חתימה לאפליקציה לניפוי באגים. כשמריצים או מנפים באגים באפליקציה ב-Android Studio, Android Studio יוצר באופן אוטומטי אישור לחתימת אפליקציה שמיועד לפיתוח ולניפוי באגים. הסבר מלא זמין במאמר בנושא Android Studio: חתימה על גרסת ה-debug של ה-build.

    מחברים את הנייד למחשב המקומי. בקטע Android Studio יופיעו המכשירים המחוברים לפי מספר הדגם. בוחרים את המכשיר מהרשימה ולוחצים על הפעלת הפרויקט. הפעולה הזו יוצרת ומתקינה את אפליקציית הדוגמה במכשיר הנייד.

    הוראות מפורטות זמינות במאמר הרצת אפליקציות במכשיר חומרה באתר Android Developers.

    עכשיו מפסיקים את האפליקציה הפעילה.

  2. כדי לקבל את טביעת האצבע של אישור הניפוי באגים בפורמט SHA-1, פועלים לפי ההוראות שמפורטות במאמר ניהול לקוחות OAuth / סוגי אפליקציות / אפליקציות מקוריות / Android באתר העזרה של מסוף Google Cloud.

  1. במסוף Google Cloud, עוברים אל מרכז הבקרה לבחירת הפרויקט ובוחרים את הפרויקט שבו רוצים להשתמש כדי ליצור פרטי כניסה ל-OAuth.
  2. עוברים לדף APIs and Services (ממשקי API ושירותים) ולוחצים על Credentials (אמצעי אימות) בתפריט הניווט.

  3. אם עדיין לא הגדרתם את מסך ההסכמה לפרויקט הזה ב-Google Cloud, יופיע הלחצן Configure consent screen (הגדרת מסך ההסכמה). במקרה כזה, צריך להגדיר את מסך ההסכמה באמצעות התהליך הבא. אחרת, עוברים לקטע הבא.

    1. לוחצים על הגדרת מסך ההסכמה. מוצג הדף מסך הסכמה ל-OAuth.
    2. בהתאם לתרחיש השימוש, בוחרים באפשרות פנימי או חיצוני ולוחצים על יצירה. מוצגת החלונית OAuth consent screen (מסך הסכמה ל-OAuth).
    3. מזינים את המידע בדף פרטי האפליקציה בהתאם להוראות שמופיעות במסך, ואז לוחצים על שמירה והמשך. החלונית Scopes מוצגת.
    4. אין צורך להוסיף היקפי הרשאה, לכן לוחצים על שמירה והמשך. החלונית משתמשי בדיקה מוצגת.
    5. לוחצים על קהל ואז על הלחצן + הוספת משתמשים.
    6. מזינים את כתובת האימייל של משתמש הבדיקה ולוחצים על הלחצן שמירה.
    7. לוחצים על שמירה והמשך. מוצגת החלונית סיכום.
    8. בודקים את המידע במסך ההסכמה ל-OAuth ולוחצים על חזרה ללוח הבקרה.

פרטים מלאים זמינים במאמר הגדרת מסך הסכמה ל-OAuth באתר העזרה של Google Cloud Console. לפני שממשיכים, חשוב להוסיף לפחות משתמש אחד לבדיקה.

הגדרת פרטי כניסה ב-OAuth

  1. כדי לרשום את אפליקציית הדוגמה ל-OAuth 2.0 וליצור פרטי כניסה ל-OAuth, פועלים לפי ההוראות במאמר הגדרת OAuth 2.0.
    1. מציינים את סוג האפליקציה, שהוא אפליקציה מקורית/אפליקציית Android.
    2. מוסיפים את טביעת האצבע של SHA-1 ללקוח OAuth לפי ההוראות במאמר הגדרת OAuth 2.0 / אפליקציות מקוריות / Android באתר העזרה של Google Cloud Console. במהלך תהליך הפיתוח, צריך ליצור את מפתח SHA-1 ממפתח ברירת המחדל של Android Studio.

הפעלת האפליקציה

  1. כשהמכשיר הנייד מחובר למכונה המקומית, לוחצים שוב על Run project כדי להריץ את אפליקציית הדוגמה במכשיר הנייד.

אחרי ההתקנה, האפליקציה זמינה במכשיר הנייד בשם Home API Sample App.