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

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

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

חשוב לוודא שאתם עומדים בדרישות המינימליות לשימוש בממשקי 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 Developer. השדות האחרים הם אופציונליים ואפשר להשאיר אותם ריקים.
    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. פורקים את ה-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 Portal.
    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