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

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

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

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

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

הורדת Xcode

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

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

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

  • ‫macOS Sonoma ואילך
  • ‫Xcode 15.3 ואילך

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

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

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

לפרטים נוספים, קראו את המאמר Create a development provisioning profile של אפל בנושא פרופילי הקצאה.

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

  1. יוצרים מזהה של קבוצת אפליקציות כדי שהאפליקציה תוכל לתקשר עם MatterExtension.
    1. נכנסים לפורטל המפתחים של אפל.
    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 והפעלת ממשקי Home API

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

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

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

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

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

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

    הגדרת מסך OAuth

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

הפעלת ממשקי ה-API של Home

מפעילים גישה לממשקי ה-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. פורקים את ה-SDK שהורדתם לתיקייה ThirdParty/GoogleHomeSDK ביחס לתיקיית השורש של הפרויקט.
  2. מגדירים את מזהה המפתח ואת מזהה הלקוח ב-OAuth:
    1. בחלונית הניווט, מחפשים את התיקייה GoogleHomeAPISampleIOS ופותחים את הקובץ Info.plist לעריכה.

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

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

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

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

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

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

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

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

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

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

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

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

  8. מגדירים את היקף ההרשאות של OAuth ב-GoogleHomeAPISampleIOS.swift. כברירת מחדל, קוד המקור של אפליקציית הדוגמה משתמש בהיקף ההרשאות https://www.googleapis.com/auth/home.platform.v2. הרבה תכונות באפליקציה לדוגמה מוגבלות על ידי ההיקף home.platform.v2, וצריך אישור מהשותף כדי לגשת אליהן. כדי להריץ את אפליקציית הדוגמה עם ההיקף הרגיל https://www.googleapis.com/auth/home.platform.selected.devices, פותחים את GoogleHomeAPISampleIOS.swift ומשנים את homePlatformOAuthScope ב-Home.configure ל-HomePlatformOAuthScope.v1:

    Home.configure {
  $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
  $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
  ...
}