יצירת אפליקציה לדוגמה ל-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.
    2. מזינים את המידע בדף פרטי האפליקציה בהתאם להוראות שמופיעות במסך, ואז לוחצים על שמירה והמשך. יוצג החלונית Scopes (היקפי גישה).
    3. אין צורך להוסיף היקפי הרשאה, אז לוחצים על שמירה והמשך. החלונית משתמשי בדיקה מוצגת.
    4. אם בחרתם ליצור מסך בקשת הסכמה פנימי, אתם צריכים להוסיף משתמשים כדי לבדוק את הגישה לאפליקציה. לוחצים על הוספת משתמשים. מוצג החלונית הוספת משתמשים. למשתמשי בדיקה יש הרשאה להעניק הרשאות באפליקציה. בשדה הריק, מוסיפים כתובת אימייל אחת או יותר של חשבון Google ולוחצים על הוספה.
    5. לוחצים על שמירה והמשך. מוצגת החלונית סיכום.
    6. בודקים את המידע במסך ההסכמה ל-OAuth ולוחצים על חזרה ללוח הבקרה.

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

    הגדרת מסך OAuth

    1. לוחצים על הלחצן CREATE CREDENTIALS (יצירת פרטי כניסה) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth).
      1. בקטע סוג האפליקציה, בוחרים באפשרות iOS.
    2. מזינים את מזהה החבילה עם מזהה האפליקציה ועם מזהה הצוות של מפתחי Apple. השדות האחרים הם אופציונליים ואפשר להשאיר אותם ריקים.
    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 לפרויקט

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

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

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

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

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

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

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

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

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

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

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

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