1. מבוא
מהם ממשקי Home API?
ממשקי ה-API של Google Home מספקים קבוצה של ספריות שמאפשרות למפתחים להשתמש בסביבה העסקית של Google Home. באמצעות ממשקי ה-API של Home, מפתחים יכולים ליצור אפליקציות שמאפשרות להפעיל מכשירים לבית חכם ולשלוט בהם בצורה חלקה.
הרכיבים של Home APIs
ממשקי ה-API של Home מורכבים מ:
- ממשקי API של מכשיר ומבנה: אינטראקציה עם הבית של המשתמש. אפליקציות יכולות להשתמש בממשקי ה-API האלה כדי לקרוא מידע על מכשירים, חדרים ומבנים (לדוגמה, לראות את הטמפרטורה הנוכחית בתרמוסטט) ולשלוט במכשירים (לדוגמה, לשנות את הטמפרטורה לשמירה בתרמוסטט).
- Commissioning API: הוספה (הגדרה) של מכשירים חדשים של Matter ל-Matter Fabric במאמץ מינימלי.
- Automation API: יצירת פעולות אוטומטיות, מחיקה שלהן ושליחת שאילתות אליהן שפועלות בבית של המשתמש.
דרישות מוקדמות
- הגרסה היציבה האחרונה של Xcode.
- חשבון Google עם מבנה אחד לפחות בבית.
- מכשיר iOS עם iOS מגרסה 16.4 ואילך, שהוגדרה בו חשבון הבדיקה.
- חשבון Apple ID שמשויך ל תוכנית המפתחים של Apple כדי ליצור את פרופיל ההקצאה.
- מרכז Google שתומך בממשקי Home API.
מה תלמדו
- איך יוצרים אפליקציה ל-iOS באמצעות ממשקי ה-API של Home, עם שיטות מומלצות.
- איך משתמשים ב-Device API וב-Structure API כדי לייצג בית חכם ולשלוט בו.
- איך משתמשים ב-Commissioning API כדי להוסיף מכשירים לסביבה העסקית של Google Home.
- איך משתמשים ב-Automation API כדי ליצור פעולה אוטומטית בסיסית.
2. הגדרת הבית
הכנת המכשירים
Google Home Playground מציע מגוון של מכשירי בית חכם מודמלים מראש, והוא מומלץ לבדיקה של מלוא הפוטנציאל של ממשקי ה-API של Home, במיוחד אם יש לכם מספר מוגבל של מכשירים בבית.
פועלים לפי ההוראות כדי להיכנס ל-Google Home Playground ומשלימים את קישור החשבון באפליקציית Google Home. בסיום, המכשירים אמורים להופיע בכרטיסייה 'מכשירים' באפליקציית Google Home.
3. תהליך ההגדרה
אחזור הקוד של האפליקציה לדוגמה
מתחילים בהעתקה (cloning) של קוד המקור מ-GitHub:
git clone https://github.com/google-home/google-home-api-sample-app-ios.git
ספריית הדוגמה מכילה שני סניפים, start
ו-finished
, לקודלאב הזה.
start
: הקוד הראשוני של הפרויקט, שבו תבצעו שינויים כדי להשלים את הקודלאב.finished
: הקוד המלא של הקודלאב הזה, שמשמש לבדיקה של העבודה שלכם.
הסבר על הקוד 'start'
כדי להתחיל את הקודלאב, עוברים להסתעפות start
של המאגר שהעתקתם:
git checkout start
ההסתעפות הזו מכילה את קוד ההתחלה של הפרויקט. במהלך הקודלאב, תשנו את הקוד הזה כדי להטמיע את הפונקציונליות המלאה. אפליקציית הדוגמה ב-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
) ולכלי עזר אחרים.
במהלך הקודלאב הזה, תראו תגובות כמו TODO
או אזהרות וחסימות קוד בפרויקט start
. הם מסמנים את הקטעים שבהם תוסיפו קוד או תבטלו את ההערה שלו כדי להטמיע את הפונקציונליות הנדרשת, לפי השלבים שמפורטים.
יצירת קובצי תצורה לפריסה של Apple
כדי להגדיר את App Attest, פועלים לפי ההוראות ליצירת קובצי תצורה לפריסה של Apple. חשוב לזכור: אחרי ההגדרה, אפשר לפרוס את האפליקציה רק במכשיר אמיתי, ולא בסימולטור.
מגדירים אימות
כדי לקבל את מזהה הלקוח של OAuth ולהפעיל את Home APIs, צריך קודם להיכנס ל-Google Cloud וליצור פרויקט חדש או לבחור פרויקט קיים. לאחר מכן, פועלים לפי השלבים המפורטים כדי ליצור את מזהה הלקוח של OAuth ולהפעיל את ממשקי ה-API של Home ולהוסיף את החשבון שלכם לרשימת ההיתרים.
הגדרת ה-SDK
מורידים את Home APIs iOS SDK ומגדירים אותו לפי ההוראות שמפורטות בקטע הגדרת ה-SDK. חשוב לזכור להחליף את HOME_API_TODO_ADD_APP_GROUP
בקבוצת האפליקציות שלכם.
פיתוח והרצה של הפרויקט
אחרי היצירה וההרצה של הפרויקט באמצעות ההסתעפות start
, אמורה להופיע תיבת דו-שיח של TODO
ומסך עם הכיתוב 'נדרשת כניסה'. האינטראקציה עם Home APIs תיושם בקטעים הבאים.
הערה: כדי לאתר את הקוד שצריך לשנות, מחפשים בפרויקט את הטקסט שמוצג בתיבת הדו-שיח. לדוגמה, מחפשים את הביטוי "TODO: initialize Home".
4. אתחול
איך מפעילים את הבית
לפני שמשתמשים באחד מ-Home APIs ל-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 Hub ומכשיר Matter. מוודאים שאפשר לגשת ל-Google Hub במבנה שלכם ושהמכשיר מחובר לאינטרנט. אם אין לכם מכשיר Matter, תוכלו לנסות להשתמש באפליקציה Matter Virtual Device במקום זאת.
הוספת מכשיר 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
. לוחצים על Save (שמירה) כדי ליצור את האוטומציה באמצעות structure.createAutomation()
.
הערה: הפעולות האוטומטיות הזמינות תלויות במכשירים בבית. אם לא מופיעות פעולות אוטומטיות זמינות, נסו לשנות את השם של מנורת הלד ל-'light2'.
חוזרים לכרטיסייה 'מכשירים' ומפעילים את הנורה שנקראת 'light2'. הוא יכבה באופן אוטומטי אחרי חמש שניות.
הרכיבים של תהליך אוטומציה הם:
- אירוע של סימן לתחילת פעולה: זהו אירוע שמפעיל את האוטומציה. בדוגמה הזו, הפעולה האוטומטית תתחיל ברגע שיהיה שינוי ב-
OnOffTrait
. - תנאי: הבדיקה הזו בודקת אם מכשיר ה-Starter עומד בדרישות ספציפיות. במקרה כזה, הפעולה האוטומטית תתבצע אם הנורה דולקת.
- פעולה: זו הפעולה האוטומטית שרוצים לבצע, אבל רק אם ה-starter עומד בדרישות. אם התנאים מתקיימים, הנורה תיכבה.
דוגמאות נוספות מפורטות בדף דוגמאות לאוטומציה.
מחיקת פעולה אוטומטית
שיטת structure.deleteAutomation()
מופעלת כשמחליקים שמאלה על תהליך אוטומציה קיים ומקישים על סמל האשפה כדי להסיר אותו מהמבנה.
8. מזל טוב
מעולה! סיימתם ליצור אפליקציה בסיסית לבית חכם באמצעות ממשקי Home API ל-iOS.
מה השלמת:
- הפעלה: חיברתם את האפליקציה לסביבה העסקית של Google Home באמצעות
Home.connect()
. - הרשאות: טיפול באימות ובהרשאה של משתמשים לגשת לנתוני הבית.
- מכשירים ומבנים: אחזור וחשיפת חדרים ומכשירים באמצעות
home.rooms()
ו-home.devices()
. - שליטה במכשיר: הטמעת אינטראקציה עם המכשיר, כמו החלפת המצב של
OnOffPluginUnitDeviceType
באמצעות קריאה לפקודות על המאפיינים שלו. - ניהול המבנה: נוספה פונקציונליות ליצירת חדרים חדשים (
structure.createRoom()
), להעברת מכשירים בין חדרים (structure.move()
) ולמחיקה של חדרים ריקים (structure.deleteRoom()
). - הפעלה: שילוב תהליך ההפעלה של ה-SDK כדי להוסיף מכשירי Matter חדשים (
MatterAddDeviceRequest
). - אוטומציה: הוסבר איך להציג רשימה של תרחישי אוטומציה בתוך מבנה, ליצור אותם (
structure.createAutomation()
) ולמחוק אותם (structure.deleteAutomation()
).
עכשיו יש לכם הבנה בסיסית לגבי האופן שבו אפשר להשתמש ב-Home APIs כדי ליצור חוויות בקרה עשירות על הבית החכם ב-iOS.
השלבים הבאים:
- לבדוק איך שולטים בסוגי מכשירים אחרים שמוצגים באפליקציית הדוגמה (מנורות, מאווררים, תריסים וכו').
- מידע נוסף על המאפיינים והפקודות השונים שזמינים במכשירים שונים.
- אפשר להתנסות ביצירת תהליכים אוטומטיים מורכבים יותר באמצעות תנאים, פעולות וגורמים מפעילים שונים.
- במסמכי העזרה של ממשקי ה-API של Home מפורט מידע נוסף על תכונות מתקדמות.
כל הכבוד!