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

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

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

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

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

הורדת Xcode

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

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

כדי שהאפליקציה תזדהה מול הקצה העורפי של האימות ב-Google, היא צריכה מזהה לקוח OAuth. ב-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 כבר הוגדר וסטטוס הפרסום שלו הוא Testing, ודאו שחשבונות הבדיקה שבהם תשתמשו נוספו לקבוצה Test users. אם לא, עוברים לשלב הבא.

    1. בהתאם לתרחיש לדוגמה, בוחרים באפשרות Internal או External ולוחצים על Create. מופיע החלונית מסך הסכמה של OAuth.
    2. מזינים את המידע בדף פרטי האפליקציה לפי ההוראות במסך, ולוחצים על שמירה והמשך. החלונית Scopes נפתחת.
    3. אין צורך להוסיף היקפי הרשאות, אז לוחצים על שמירה והמשך. החלונית Test users מוצגת.
    4. אם בחרתם ליצור מסך הסכמה פנימי, אתם צריכים להוסיף משתמשים כדי לבדוק את הגישה לאפליקציה. לוחצים על Add users. החלונית Add users נפתחת. למשתמשי הבדיקה יש הרשאה להעניק הרשאות באפליקציה. בשדה הריק, מוסיפים כתובת האימייל בחשבון Google אחת או יותר, ואז לוחצים על הוספה.
    5. לוחצים על שמירה והמשך. החלונית Summary נפתחת.
    6. בודקים את הפרטים במסך ההסכמה ל-OAuth ולוחצים על Back to dashboard.

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

    הגדרת מסך OAuth

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

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

מפעילים את הגישה ל-Home APIs.

  1. בכרטיסייה APIs and Services, לוחצים על Enabled APIs & Services.
  2. לוחצים על ENABLE APIS AND SERVICES בחלק העליון של הדף.
  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. פורקים את ה-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. לוחצים על הכרטיסייה Signing and Capabilities בחלק העליון ובוחרים את היעד GoogleHomeAPISampleIOS בצד שמאל בקטע TARGETS.
    4. בקטע Signing, בוחרים בשדה Bundle Identifier ומזינים את המזהה הייחודי של האפליקציה.
    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
  ...
}