פיתוח אפליקציה לנייד באמצעות ממשקי ה-API של Home ב-iOS

1. מבוא

מהם ממשקי ה-API של Home?

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

בסרטון הזה מוצגת הדרכה מפורטת קצרה של האפליקציה לנייד שתבנו, לכן מומלץ לצפות בסרטון תוך כדי ביצוע ההוראות ב-Codelab.

רכיבים של Home APIs

ממשקי ה-API של Home מורכבים מהרכיבים הבאים:

• ממשקי Device ו-Structure API: אינטראקציה עם הבית של המשתמש. אפליקציות יכולות להשתמש בממשקי ה-API האלה כדי לקרוא מידע על מכשירים, חדרים ומבנים (לדוגמה, לראות את הטמפרטורה הנוכחית של התרמוסטט) ולשלוט במכשירים (לדוגמה, לשנות את הטמפרטורה לשמירה בתרמוסטט).
• ‫Commissioning API: הפעלה (הגדרה) של מכשירי Matter חדשים ב-fabric במאמץ מינימלי.
• ‫Automation API: יצירה, מחיקה ושאילתות של פעולות אוטומטיות שפועלות בבית של המשתמש.

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

• הגרסה היציבה העדכנית של Xcode.
• חשבון Google שיש בו לפחות מבנה אחד בבית.
• מכשיר iOS עם גרסה 16.4 ומעלה של iOS שהוגדר עם חשבון הבדיקה.
• ‫Apple ID שרשום ב תוכנית למפתחים של אפל כדי ליצור את פרופיל ההקצאה.
• מרכז של Google שתומך בממשקי Home API.

מה תלמדו

• איך לפתח אפליקציה ל-iOS באמצעות ממשקי Home API, עם שיטות מומלצות.
• איך משתמשים בממשקי ה-API של מכשירים ומבנים כדי לייצג בית חכם ולשלוט בו.
• איך משתמשים ב-Commissioning API כדי להוסיף מכשירים לאקוסיסטם של Google Home.
• איך משתמשים ב-Automation API כדי ליצור אוטומציה בסיסית.

2. הגדרת הבית

הכנת המכשירים

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

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

3. תהליך ההגדרה

קבלת הקוד של אפליקציה לדוגמה

מתחילים בשיבוט קוד המקור מ-GitHub:

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

ספריית הדוגמה מכילה שני ענפים, start ו-finished, ל-codelab הזה.

• ‫start: קוד לתחילת הדרך של הפרויקט הזה, שבו תבצעו שינויים כדי להשלים את ה-Codelab.
• ‫finished: הקוד המלא של ה-Codelab הזה, שמשמש לבדיקת העבודה.

הסבר על קוד ההתחלה

כדי להתחיל את ה-codelab הזה, צריך לעבור לענף start של המאגר המשוכפל:

git checkout start

הענף הזה מכיל את קוד לתחילת הדרך של הפרויקט. תשנו את הקוד הזה במהלך ה-codelab כדי להטמיע את הפונקציונליות המלאה. אפליקציית הדוגמה של Codelab מספקת מבנה בסיסי שנבנה ב-Swift לאינטראקציה עם Home APIs iOS SDK. בואו נסתכל על הרכיבים העיקריים בפרויקט start:

• ‫Main Entry (GoogleHomeAPISampleIOSApp): נמצא ב-GoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift, זו נקודת הכניסה הראשית לאפליקציה. הוא מגדיר ומפעיל את ה-SDK ומגדיר את ממשק המשתמש הראשי.
• Core Views (View/):
  • ‫MainView.swift: תצוגת הבסיס אחרי ההפעלה, שמכילה את NavigationView הראשי. הוא מטפל בבחירת הבית הווירטואלי הפעיל ב-Google Home ומציג את StructureView המתאים.
  • ‫StructureView.swift: מוצג התוכן של המבנה שנבחר כרגע, באמצעות כרטיסיות למעבר בין רשת של מכשירים לבין רשימת הפעולות האוטומטיות. יש גם תפריטים להוספת חדרים או מכשירים.
  • ‫DeviceView.swift: מייצג את המשבצת האינטראקטיבית של מכשיר יחיד ברשת StructureView.
  • ‫AutomationsView.swift: מציג את רשימת הפעולות האוטומטיות הקיימות במבנה, ומאפשר ליצור פעולה אוטומטית חדשה או להציג את פרטי הפעולות האוטומטיות הקיימות.
• ‫ViewModels (ViewModel/): המחלקות האלה מנהלות את המצב והלוגיקה של התצוגות.
  • ‫AccountViewModel.swift: מטפל בחיבור לאובייקט Home ומנהל את מצב האימות.
  • ‫MainViewModel.swift: ניהול רשימת האובייקטים הזמינים Structure ומעקב אחרי המבנה שנבחר.
  • ‫StructureViewModel.swift: ניהול התצוגה של חדרים ואובייקטים של DeviceControl במבנה שנבחר.
  • ‫AutomationList.swift, AutomationViewModel.swift וכן הלאה: מטפל באחזור, בהצגה, ביצירה ובניהול של אוטומציות.
• Device Controls (ViewModel/Device/):
  • ‫DeviceControl.swift: מחלקה בסיסית לייצוג מכשירים שאפשר לשלוט בהם בממשק המשתמש.
  • תת-מחלקות ספציפיות (LightControl.swift, FanControl.swift, OnOffPlugInUnitControl.swift וכן הלאה): הטמעה של הלוגיקה של ממשק המשתמש, שליטה במכשיר ומיפוי מצב לסוגים שונים של מכשירים על סמך המאפיינים שלהם.
  • DeviceControlFactory.swift: אחראי ליצירת מחלקת המשנה המתאימה DeviceControl עבור HomeDevice נתון.
• Commissioning (Commissioning/):
  • ‫CommissioningManager.swift: מכיל את הלוגיקה לניהול תהליך ההפעלה של מכשיר Matter.
• ‫Utilities & UX (Utils/, UX/, Storage/): מכיל קוד עזר לרכיבי ממשק משתמש (צבעים, מידות), טיפול בשגיאות, אחסון נתונים (SelectedStructureStorage.swift) וכלי עזר אחרים.

במהלך ה-codelab הזה, תראו הערות כמו TODO או בלוקים של קוד שהוסרו מההערות והתראות בפרויקט start. התגים האלה מציינים את החלקים שבהם צריך להוסיף קוד או לבטל סימון כהערה (uncomment) של הקוד כדי להטמיע את הפונקציונליות הנדרשת, בהתאם לשלבים שמופיעים בהמשך.

יצירת קובצי תצורה לפריסה של Apple

כדי להגדיר את App Attest, פועלים לפי ההוראות ליצירת קבצים להגדרת פריסה של אפליקציות של אפל. שימו לב: אחרי ההגדרה, אפשר לפרוס את האפליקציה רק במכשיר אמיתי, ולא בסימולטור.

מגדירים אימות

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

הגדרת ה-SDK

משיגים את Home APIs iOS SDK ומגדירים אותו לפי הוראות ההגדרה שמופיעות במאמר הגדרת ה-SDK. חשוב לזכור להחליף את HOME_API_TODO_ADD_APP_GROUP בקבוצת האפליקציות שלכם.

בנייה והרצה של הפרויקט

אחרי שיוצרים את הפרויקט ומריצים אותו באמצעות ההסתעפות start, אמורות להופיע תיבת דו-שיח TODO ומסך עם הכיתוב 'נדרשת כניסה'. האינטראקציה עם ממשקי ה-API של Home תיושם בקטעים הבאים.

הערה: כדי למצוא את הקוד שצריך לשנות, מחפשים בפרויקט את הטקסט שמוצג בתיבת הדו-שיח. לדוגמה, מחפשים את המחרוזת "TODO: initialize Home".

4. אתחול

הפעלת הבית

לפני שמשתמשים באחד מממשקי ה-API של Home ל-iOS, צריך לאתחל את Home באפליקציה. Home הוא נקודת הכניסה ברמה העליונה ל-SDK ומספק גישה לכל הישויות במבנה של המשתמש. כשמבקשים את כל הישויות מסוג מסוים, ה-API מחזיר אובייקט Query שמאפשר לבחור איך לקבל את התוצאות. ב-GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift, מסירים את התגובה ואת ההתראה ב-connect() כדי להטמיע את ההגדרה של הבית.

  /// TODO: initialize Home
  /// Remove comments to initialize Home and handling permission.
  private func connect() {
    Task {
      do {
        self.home = try await Home.connect()
      } catch {
        Logger().error("Auth error: \(error).")
      }
    }
  }

הרשאה לשימוש בממשקי ה-API של Home

מסך ההסכמה יופיע כשמפעילים את האפליקציה. בוחרים את הבית הווירטואלי של Google Home ובוחרים את החשבון שנמצא ברשימת ההיתרים של פרויקט Google Cloud.

5. מכשירים ומבנים

קבלת חדרים ומכשירים

ב-GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, מסירים את התגובה ואת ההתראה ב-getRoomsAndDevices() כדי לקבל את החדרים והמכשירים במבנה שנבחר עם home.rooms() ו-home.devices(), בהתאמה.

  /// TODO: get rooms and devices
  /// Remove comments to get the rooms and devices from home entry
  private func getRoomsAndDevices(){
    self.home.rooms().batched()
      .combineLatest(self.home.devices().batched())
      .receive(on: DispatchQueue.main)
      .catch { error in
        Logger().error("Failed to load rooms and devices: \(error)")
        return Just((Set<Room>(), Set<HomeDevice>()))
      }
      .map { [weak self] rooms, devices in
        guard let self = self else { return [] }
        self.hasLoaded = true
        return self.process(rooms: rooms, devices: devices)
      }
      /// receive from .map and .assign() to publisher entries
      .assign(to: &self.$entries)
  }

הפונקציה process() מוודאת קודם שהמכשירים נמצאים באותו חדר, ורק אז גורמת להם לקיים אינטראקציה כHomeDevices באמצעות DeviceControl ו-DeviceControlFactory.

הערה: אם המכשיר שלכם לא מופיע בDeviceControlFactory, הוא יוצג כ'לא נתמך'. מידע נוסף על מכשירים נתמכים זמין בדף סוגי מכשירים נתמכים ב-iOS.

אינטראקציה עם מכשיר

התוסף outlet1 לא פעיל בהתחלה כשמקישים על המכשירים או מחליקים עליהם. כדי לאפשר אינטראקציה עם הרכיב, מאתרים את GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift ומסירים את ההערה וההתראה בתוך הפונקציה primaryAction().

  /// TODO: primary action of OnOffPlug
  /// Toggles the plug; usually provided as the `action` callback on a Button.
  public override func primaryAction() {
    self.updateTileInfo(isBusy: true)
    Task { @MainActor [weak self] in
      guard
        let self = self,
        let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
        let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
      else { return }

      do {
        try await onOffTrait.toggle()
      } catch {
        Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
        self.updateTileInfo(isBusy: false)
      }
    }
  }

הפונקציה primaryAction(), שנמצאת במחלקה OnOffPlugInUnitControl, מחליפה את מצב ההפעלה/ההשבתה של שקע חכם או של כל מכשיר שמיוצג על ידי OnOffPluginUnitDeviceType.

דוגמאות נוספות לשליטה במכשיר זמינות במאמר GoogleHomeAPISampleIOS/ViewModel/Device.

יצירת חדר חדש

Structure API מאפשר ליצור ולמחוק חדרים, וגם להעביר מכשירים בין חדרים.

בGoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, מסירים את התגובה ואת ההתראה בaddRoom().

  /// TODO: add room
  /// Add a new room in a given structure.
  func addRoom(name: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.createRoom(name: name)
      } catch {
        Logger().error("Failed to create room: \(error)")
      }
    }
  }

כדי ליצור מרחב חדש עם structure.createRoom(), עוברים לפינה הימנית העליונה ולוחצים על הסמל + > הוספת מרחב. מזינים את השם החדש של החדר ולוחצים על 'יצירת חדר'. החדר החדש יופיע אחרי כמה שניות.

העברת המכשיר לחדר אחר

בGoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, מסירים את התגובה ואת ההתראה בmoveDevice().

  /// TODO: move device
  /// Move a device into a different room.
  func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
    Task {
      do {
        _ = try await structure.move(device: deviceID, to: roomID)
      } catch {
        Logger().error("Failed to move to room: \(error)")
      }
    }
  }

כדי להעביר את המכשיר באמצעות structure.move(), לוחצים עליו לחיצה ארוכה, בוחרים באפשרות 'העברה לחדר אחר' ובוחרים את החדר החדש.

מחיקת חדר ריק

בGoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, מסירים את התגובה ואת ההתראה בremoveRoom().

  /// TODO: delete room
  /// Delete an empty room in a given structure.
  func removeRoom(id: String, structure: Structure) {
    Task {
      do {
        // The view will be updated with the values from the devices publisher.
        _ = try await structure.deleteRoom(id: id)
      } catch {
        Logger().error("Failed to remove room: \(error)")
      }
    }
  }

כדי למחוק חדר ריק עם structure.deleteRoom(), לוחצים על סמל האשפה משמאל לשם החדר ומאשרים את הפעולה. לתשומת ליבכם, אפשר למחוק רק חדרים ריקים.

הערה: כדי ליצור חדר ריק, צריך להזיז את המכשיר בחזרה.

6. הפעלה

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

הוספת מכשיר Matter

Commissioning API מאפשר לאפליקציה שלכם להוסיף מכשירי Matter חדשים לבית של המשתמש ולחשבון Google שלו. כך תוכלו ליהנות מחוויית הגדרה חלקה ישירות באפליקציה.

בGoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift, מסירים את התגובה ואת ההתראה בaddMatterDevice().

  /// TODO: add Matter Device
  /// Starts the Matter device commissioning flow to add the device to the user's home.
  /// - Parameters:
  ///   - structure: The structure to add the device to.
  ///   - add3PFabricFirst: Whether to add the device to a third party fabric first.
  public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
    self.isCommissioning = true

    /// pass if it's 1p or 3p commissioning
    let userDefaults = UserDefaults(
      suiteName: CommissioningManager.appGroup)
    userDefaults?.set(
    add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)

    Task {
      do {
        try await structure.prepareForMatterCommissioning()
      } catch {
        Logger().error("Failed to prepare for Matter Commissioning: \(error).")
        self.isCommissioning = false
        return
      }

      // Prepare the Matter request by providing the ecosystem name and home to be added to.
      let topology = MatterAddDeviceRequest.Topology(
        ecosystemName: "Google Home",
        homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
      )
      let request = MatterAddDeviceRequest(topology: topology)

      do {
        Logger().info("Starting MatterAddDeviceRequest.")
        try await request.perform()
        Logger().info("Completed MatterAddDeviceRequest.")
        let commissionedDeviceIDs = try structure.completeMatterCommissioning()
        Logger().info("Commissioned device IDs: \(commissionedDeviceIDs).")
      } catch let error {
        structure.cancelMatterCommissioning()
        Logger().error("Failed to complete MatterAddDeviceRequest: \(error).")
      }

      self.isCommissioning = false
    }
  }

כדי ליצור מרחב חדש עם structure.prepareForMatterCommissioning(), עוברים לפינה הימנית העליונה ולוחצים על הסמל '+' > הוספת מכשיר ל-Google Fabric. הוא משתמש ב-MatterAddDeviceRequest כדי להוסיף את מכשיר Matter לחדר. אחרי שבוחרים את החדר ואת שם המכשיר, המכשיר מוצג במסך 'מכשירים'.

7. אוטומציה

צפייה בכל האוטומציות במבנה

מקישים על אוטומציות בסרגל הניווט התחתון. כל הפעולות האוטומטיות במבנה יופיעו ברשימה עם structure.listAutomations().

הערה: אם לא הגדרתם אוטומציות לבית, תופיע ההודעה 'כדי להתחיל, צריך להוסיף אוטומציה'.

יצירת פעולה אוטומטית

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

ב-GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift, מסירים את התגובה, את ההתראה ואת הפעולה האוטומטית הריקה ב-lightAutomation().

  /// TODO: create automation
  /// - Parameter devices: devices in current selected structure
  /// - Returns: the automation object to be created
  /// This automation will turn off the light after 5 seconds.
  public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
    let light = devices.first { $0.name == "light2" }
    
    guard let light else {
      Logger().error("Unable to find light device with name light2")
      throw HomeError.notFound("No devices support OnOffLightDeviceType")
    }
    
    return automation(
      name: "Turn off light after 5 seconds",
      description:
        """
        Turns off light2 after it has been on for 5 seconds.
        """
    ) {
      let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
      onOffStarter
      condition {
        onOffStarter.onOff.equals(true)
      }
      delay(for: Duration.seconds(5))
      action(light, OnOffLightDeviceType.self) {
        OnOffTrait.off()
      }
    }
  }

כדי ליצור אוטומציה שתכבה את האור חמש שניות אחרי שהוא נדלק, עוברים לתצוגת האוטומציה ולוחצים על הלחצן + הוספה. לאחר מכן, בוחרים באפשרות כיבוי האור אחרי 5 שניות. יוצגו פרטי האוטומציה, כולל starter, condition ו-action. לוחצים על שמירה כדי ליצור את הפעולות האוטומטיות באמצעות structure.createAutomation().

הערה: הפעולות האוטומטיות שזמינות לכם תלויות במכשירים שיש לכם בבית. אם לא מופיעות אוטומציות זמינות, נסו לשנות את השם של מכשיר התאורה ל-light2.

חוזרים לכרטיסייה 'מכשירים' ומפעילים את הנורה שנקראת light2. הוא יושבת אוטומטית אחרי חמש שניות.

הרכיבים של אוטומציה הם:

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

דוגמאות נוספות זמינות בדף דוגמאות לאוטומציות.

מחיקת פעולה אוטומטית

השיטה structure.deleteAutomation() מופעלת כשמחליקים שמאלה על אוטומציה קיימת ומקישים על סמל הפח כדי להסיר אותה מהמבנה.

8. מזל טוב

מעולה! יצרתם בהצלחה אפליקציית בית חכם בסיסית באמצעות Home APIs ל-iOS.

מה השגתם:

• הפעלה ראשונית: חיברתם את האפליקציה למערכת האקולוגית של Google Home באמצעות Home.connect().
• הרשאות: טיפול באימות משתמשים ובהרשאות גישה לנתונים בבית.
• מכשירים ומבנים: חדרים ומכשירים שאוחזרו ומוצגים באמצעות home.rooms() ו-home.devices().
• שליטה במכשיר: הטמעת אינטראקציה עם המכשיר, כמו שינוי המצב של OnOffPluginUnitDeviceType על ידי קריאה לפקודות במאפיינים שלו.
• ניהול המבנה: נוספה פונקציונליות ליצירת חדרים חדשים (structure.createRoom()), להעברת מכשירים בין חדרים (structure.move()) ולמחיקת חדרים ריקים (structure.deleteRoom()).
• הפעלה: שילבנו את תהליך ההפעלה של ה-SDK כדי להוסיף מכשירי Matter חדשים (MatterAddDeviceRequest).
• אוטומציה: הסבר על האופן שבו אפשר לראות רשימה של פעולות אוטומטיות, ליצור (structure.createAutomation()) ולמחוק (structure.deleteAutomation()) פעולות אוטומטיות במסגרת מבנה.

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

השלבים הבאים:

• אפשר לנסות לשלוט בסוגים אחרים של מכשירים שמופיעים באפליקציה לדוגמה (מנורות, מאווררים, תריסים וכו').
• כדאי לעיין במידע נוסף על התכונות והפקודות השונות שזמינות במכשירים שונים.
• כדאי להתנסות ביצירת אוטומציות מורכבות יותר באמצעות חבילות למתחילים, תנאים ופעולות שונים.
• פרטים נוספים על תכונות מתקדמות זמינים במאמרי העזרה בנושא Home APIs.

כל הכבוד!