יצירת אפליקציה לדוגמה ל-iOS

באפליקציית ה-iOS לדוגמה הזו נעשה שימוש בממשקי Google Home API. במדריך הזה מוסבר איך ליצור את האפליקציה ולהפעיל אותה בפעם הראשונה.

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

חשוב לוודא שאתם עומדים בדרישות המינימליות לשימוש בממשקי Home API ל-iOS.

כדי ליצור ולהתקין את אפליקציית הדוגמה, צריך מחשב עם Xcode בגרסה 15.3 ומעלה.

הורדה של Xcode

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

  1. חשבון Google.
  2. מזהה אפל שרשום לתוכנית Apple Developer כדי ליצור קובצי הגדרות של מכשירים פיזיים. אם עדיין לא יצרתם חשבון, תצטרכו לשלם על ההרשמה, והיא עשויה להימשך עד 48 שעות.
  3. מכשיר iOS (לא סימולטור) עם iOS מגרסה 16.4 ואילך שהוגדר עם חשבון הבדיקה.
  4. רשת Wi-Fi.
  5. רכזת Google שתומכת בממשקי ה-API של Home.
  6. נתב גבולות לפרוטוקול Thread אם המכשיר שלכם דורש Thread והרכזת לא תומכת בו.
  7. לפחות סוג מכשיר נתמך אחד.

לפיתוח, תצטרכו מחשב Mac שעומד בדרישות הבאות:

  • macOS Sonoma ואילך
  • Xcode מגרסה 15.3 ואילך

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

קודם כל, צריך להפעיל את היכולת App Attest באפליקציה. לכן, אי אפשר לפרוס אותו במכשירי סימולטור. כדי לעשות זאת, צריך ליצור פרופיל הקצאת הרשאות עם ההרשאה App Attest.

שנית, צריך להפעיל את קבוצות האפליקציות כדי לאפשר תקשורת בין האפליקציה לבין MatterExtension. כדי לעשות את זה, צריך לרשום מזהה של קבוצת אפליקציות.

פרטים נוספים זמינים במאמר של Apple בנושא פרופילים של הקצאת הרשאות יצירת פרופיל הקצאת הרשאות לפיתוח.

אלה השלבים המינימליים שנדרשים כדי לפרוס אפליקציה:

  1. יוצרים מזהה של קבוצת אפליקציות כדי שהאפליקציה תוכל לתקשר עם MatterExtension.
    1. נכנסים ל-Apple Developer Portal.
    2. מוסיפים מזהה של קבוצת אפליקציות. לדוגמה, יכול להיות שהפורמט יהיה group.com.company.commissioning.
  2. רושמים את מכשיר הבדיקה בחשבון המפתח.

  3. יוצרים פרופיל ליעד של האפליקציה.

    1. בוחרים מזהה ייחודי ותיאורי לחבילת האפליקציה. לדוגמה, יכול להיות שהפורמט יהיה com.company.HomeApiSample. המזהה הזה ישמש בהמשך הקטע הזה.
    2. רישום מזהה האפליקציה. כשמופיעה בקשה, מוסיפים את היכולות App Attest ו-App Groups.

    3. עורכים את מזהה האפליקציה שנוצר ומגדירים את היכולת App Groups כדי להוסיף את המזהה של קבוצת האפליקציות הרשומות.

    4. יוצרים פרופיל הקצאת הרשאות ידנית לפיתוח לפיתוח האפליקציה. משייכים אותו למזהה האפליקציה החדש שנוצר ולמכשירי הבדיקה שנבחרו. מוודאים שיש לכם אישור מפתח כדי לחתום על האפליקציה.

  4. יוצרים פרופיל ליעד MatterExtension.

    1. בוחרים מזהה של חבילת אפליקציה ל-MatterExtension. המזהה צריך להיות זהה למזהה האפליקציה. לדוגמה, אפשר לפרמט אותו כך: com.company.HomeApiSample.MatterExtension.
    2. רישום מזהה האפליקציה. כשמופיעה בקשה, מוסיפים את היכולת App Group.
    3. עורכים את מזהה האפליקציה החדש שנוצר ומגדירים את היכולת App Groups כדי להוסיף את מזהה קבוצת האפליקציות הרשום שנוצר בשלבים הקודמים.
    4. יצירת פרופיל הקצאת הרשאות לפיתוח בשביל MatterExtension.

יצירת מזהה לקוח ב-OAuth והפעלת ממשקי API של Home

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

יצירת מזהה לקוח OAuth

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

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

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

  5. בחלונית התפריטים שמימין, לוחצים על פרטי כניסה כדי ליצור מזהה לקוח OAuth.

    הגדרת מסך OAuth

    1. לוחצים על הלחצן CREATE CREDENTIALS (יצירת פרטי כניסה) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth).
      1. בקטע סוג האפליקציה, בוחרים באפשרות iOS.
    2. מזינים את מזהה החבילה עם מזהה האפליקציה ועם Apple Developer Team ID. השדות האחרים הם אופציונליים ואפשר להשאיר אותם ריקים.
    3. לוחצים על CREATE (יצירה) ורושמים את Client ID (מזהה לקוח) שנוצר או על DOWNLOAD PLIST (הורדת PLIST). הערך הזה ישמש בהמשך להפעלת הפונקציונליות של תהליך הענקת ההרשאות. מידע נוסף זמין בקטע יצירת פרטי הרשאה.

הפעלת ממשקי ה-API של דף הבית

מפעילים גישה לממשקי ה-API של Home.

  1. בכרטיסייה APIs and Services, לוחצים על Enabled APIs & Services.
  2. לוחצים על ENABLE APIS AND SERVICES (הפעלת ממשקי API ושירותים) בחלק העליון של הדף.
  3. מחפשים את HOME API ובוחרים אותו.
  4. בדף הפרטים של Home API, לוחצים על ENABLE (הפעלה).

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

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

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

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

כדי לטעון את הפרויקט ב-Xcode, לוחצים על File (קובץ) > Open (פתיחה) ובוחרים באפשרות GoogleHomeAPISampleIOS.xcodeproj בבסיס המאגר המשוכפל.

הגדרת ה-SDK

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

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

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

כניסה לחשבון

מגדירים את פרויקט Xcode עבור אפליקציית הדוגמה:

  1. בחלונית הניווט של Xcode, בוחרים את הקובץ GoogleHomeAPISampleIOS כדי לערוך את הגדרות הפרויקט.

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

  2. לוחצים על הכרטיסייה כללי בחלק העליון ובוחרים את היעד GoogleHomeAPISampleIOS בצד ימין.

  3. גוללים למטה עד שמגיעים לקטע Frameworks, Libraries, and Embedded Content (מסגרות, ספריות ותוכן מוטמע). שני רכיבי ה-Framework של Home API אמורים להופיע ברשימה.

  4. בעמודה הטמעה, בוחרים באפשרות הטמעה וחתימה עבור GoogleHomeSDK.xcframework. את המסגרת השנייה, GoogleHomeTypes.xcframework, צריך להשאיר במצב לא להטמעה.

  5. בתחתית הרשימה, לוחצים על הסמל +.

  6. כשמופיעה בקשה, מחפשים את SafariServices.framework ולוחצים על הוספה. מוודאים שהעמודה Embed מוגדרת לערך Do Not Embed עבור הרשומה הזו.

    הטמעה וחתימה

  7. לוחצים על MatterAddDeviceExtension בקטע יעד כדי לערוך את היעד.

  8. גוללים למטה עד שמגיעים לקטע Frameworks and Libraries (מסגרות וספריות). הערך GoogleHomeSDK.xcframework אמור להופיע ברשימה.

  9. בעמודה הטמעה, בוחרים באפשרות לא להטמיע.

  10. מגדירים את מזהה הלקוח של OAuth ואת מזהה המפתח:

    1. בחלונית הניווט, מחפשים את התיקייה GoogleHomeAPISampleIOS ופותחים את הקובץ Info.plist לעריכה.

  11. בקובץ Info.plist, מאכלסים את GIDClientID במזהה לקוח OAuth (ראו את הקטע הגדרת הסכמה ל-OAuth), את Cloud Project Number במספר פרויקט הענן שמתאים לפרויקט הענן, ואת GIDTeamID במזהה הצוות של מפתחים ב-Apple של חשבון המפתחים שבו השתמשתם במהלך תהליך ההרשמה ל-OAuth.

  12. מוסיפים את היכולת App Attest:

    1. בחלונית הניווט של Xcode, בוחרים את קובץ הפרויקט GoogleHomeAPISampleIOS כדי לערוך את הגדרות הפרויקט.
    2. לוחצים על הכרטיסייה חתימה ויכולות בחלק העליון ובוחרים את GoogleHomeAPISampleIOS היעד בצד ימין בקטע TARGETS.
    3. מתחת לכרטיסייה 'חתימה ויכולות', לוחצים על + יכולת ומחפשים את App Attest.
    4. לוחצים על App Attest כדי להוסיף אותו. אם היכולת הזו לא מופיעה בחיפוש, יכול להיות שהיא כבר נוספה לפרויקט.

  13. מוסיפים את היכולת App Groups.

    הוספת קבוצות של אפליקציות

    1. עוברים לפרויקט GoogleHomeAPISampleIOS > יעד GoogleHomeAPISampleIOS.
    2. לוחצים על חתימה ויכולות > + יכולת.
    3. בוחרים את היכולת קבוצות אפליקציות.
    4. לוחצים על הסמל + בקטע App Groups (קבוצות אפליקציות) ומוסיפים את מזהה קבוצות האפליקציות של האפליקציה שהוספתם ב-Apple Developer Portal.
    5. חוזרים על השלבים האלה עבור יעד MatterAddDeviceExtension כדי להוסיף אותו לקבוצות האפליקציות.

  14. עדכון מזהה החבילה

    1. כדי להפעיל ולפרוס את אפליקציית הדוגמה בהצלחה בחומרה באמצעות פרופילים של הקצאת הרשאות ואישורים למפתחים, צריך לספק מזהה חבילה ייחודי. המזהה הזה צריך להיות זהה למזהה שמשויך לפרטי הכניסה של לקוח ה-OAuth (כפי שמופיע למעלה).
    2. בחלונית הניווט של Xcode, בוחרים את קובץ הפרויקט GoogleHomeAPISampleIOS כדי לערוך את הגדרות הפרויקט.
    3. לוחצים על הכרטיסייה חתימה ויכולות בחלק העליון ובוחרים את GoogleHomeAPISampleIOS היעד בצד ימין בקטע TARGETS.
    4. בוחרים בשדה Bundle Identifier (מזהה החבילה) בקטע Signing (חתימה) ומזינים את המזהה הייחודי של האפליקציה.
    5. בוחרים או מתקינים את פרופיל ההקצאה שקשור לחבילה עם ההרשאות הנדרשות.
    6. חוזרים על השלבים האלה לגבי היעד MatterAddDeviceExtension כדי להזין את מזהה החבילה של התוסף ולייבא את פרופיל ההקצאה הרשום שלו.

  15. מעדכנים את המזהה של קבוצת האפליקציות הרשומות בקוד.

    1. האפליקציה נדרשת להגדיר את מופע ה-SDK כדי להשתמש במזהה של קבוצת האפליקציות לתכונות כמו צירוף מכשיר. כדי להשתמש במזהה קבוצת האפליקציות שרשום ב-Apple Developer Portal, צריך לעדכן את האפליקציה. לשם כך, מחפשים את המחרוזת HOME_API_TODO_ADD_APP_GROUP ומחליפים כל מופע שלה במזהה.

    ההגדרות האלה מתבצעות בקבצים הבאים:

    • GoogleHomeAPISampleIOS.swift כשמאתחלים את ערכת ה-SDK.
    • RequestHandler.swift
    • CommissioningManager.swift