יצירת אפליקציה לדוגמה ל-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, יופיע הלחצן Configure consent screen (הגדרת מסך ההסכמה). במקרה כזה, צריך להגדיר את מסך ההסכמה באמצעות התהליך הבא. אם מסך בקשת ההסכמה של 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. הערך הזה ישמש בהמשך להפעלת הפונקציונליות של תהליך הענקת ההרשאות. מידע נוסף זמין בקטע יצירת פרטי כניסה לאימות.

הפעלת ממשקי ה-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

כדי לבנות את פרויקט אפליקציית הדוגמה, נדרש מידע נוסף. הפעולות האלה כוללות הוספה מקומית של קובצי ה-SDK Framework, מילוי הפרטים של מזהה חשבון המפתח ומילוי הפרטים של מזהה הלקוח ב-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, צריך להשאיר במצב Do Not Embed (לא להטמעה).

  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. הוספת יכולת אימות אפליקציות:

    1. בחלונית הניווט של Xcode, בוחרים את קובץ הפרויקט GoogleHomeAPISampleIOS כדי לערוך את הגדרות הפרויקט.
    2. לוחצים על הכרטיסייה חתימה ויכולות בחלק העליון ובוחרים את GoogleHomeAPISampleIOS היעד בצד ימין בקטע 'יעדים'.
    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 היעד בצד ימין בקטע 'יעדים'.
    4. בוחרים בשדה Bundle Identifier (מזהה חבילה) בקטע Signing (חתימה) ומזינים את המזהה הייחודי של האפליקציה.
    5. בוחרים או מתקינים את פרופיל ההקצאה שקשור לחבילה עם ההרשאות הנדרשות.
    6. חוזרים על השלבים האלה עבור MatterAddDeviceExtension target כדי להזין את מזהה החבילה של התוסף ולייבא את פרופיל ההקצאה הרשום שלו.

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

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

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

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