פיתוח גרסת build של האפליקציה לדוגמה ל-iOS

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

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

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

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

הורדת Xcode

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

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

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

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

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

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

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

פרטים נוספים זמינים במאמר יצירת פרופיל הקצאה לפיתוח בנושא פרופילי הקצאה של Apple.

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

  1. יוצרים מזהה קבוצת אפליקציות לאפליקציה כדי לתקשר עם MatterExtension.
    1. נכנסים לפורטל למפתחים של Apple.
    2. מוסיפים מזהה של קבוצת אפליקציות. לדוגמה, אפשר להשתמש בפורמט group.com.company.commissioning.
  2. רושמים את מכשיר הבדיקה בחשבון הפיתוח.

  3. יוצרים פרופיל ליעד של האפליקציה.

    1. בוחרים מזהה לחבילת האפליקציה. המזהה צריך להיות ייחודי ותיאורי. לדוגמה, אפשר להשתמש בפורמט com.company.HomeApiSample. המזהה הזה ישמש לאורך שאר הקטע הזה.
    2. רושמים את מזהה האפליקציה. כשמופיעה בקשה, מוסיפים את היכולות App Attest ו-App Groups.

    3. עורכים את מזהה האפליקציה החדש שנוצר ומגדירים את היכולת קבוצות אפליקציות כדי להוסיף את מזהה קבוצת האפליקציות הרשומה.

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

  4. יוצרים פרופיל ליעד MatterExtension.

    1. בוחרים מזהה לחבילת האפליקציות של MatterExtension. המזהה צריך לעבור בירושה ממזהה האפליקציה. לדוגמה, אפשר לפרמט אותו בתור com.company.HomeApiSample.MatterExtension.
    2. רושמים את מזהה האפליקציה. כשמופיעה בקשה, מוסיפים את היכולת קבוצת אפליקציות.
    3. עורכים את מזהה האפליקציה החדש שנוצר ומגדירים את היכולת קבוצות אפליקציות כדי להוסיף את מזהה קבוצת האפליקציות הרשומה שנוצר בשלבים הקודמים.
    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. בהתאם לתרחיש לדוגמה, בוחרים באפשרות פנימי או חיצוני ולוחצים על Create. החלונית מסך הסכמה ל-OAuth תוצג.
    2. מזינים את הפרטים בדף פרטי האפליקציה לפי ההוראות במסך, ואז לוחצים על שמירה והמשך. חלונית ההיקפים תוצג.
    3. אין צורך להוסיף היקפי גישה, לכן לוחצים על Save and continue (שמירה והמשך). החלונית משתמשי בדיקה תוצג.
    4. אם בחרתם ליצור מסך פנימי לבקשת הסכמה, עליכם להוסיף משתמשים כדי לבדוק את הגישה לאפליקציה. לוחצים על הוספת משתמשים. החלונית הוספת משתמשים תוצג. למשתמשי הבדיקה יש הרשאה להעניק הרשאות באפליקציה. בשדה הריק, מוסיפים כתובת אימייל אחת או יותר של חשבון Google ולוחצים על הוספה.
    5. לוחצים על שמירה והמשך. החלונית Summary תופיע.
    6. בודקים את המידע במסך ההסכמה ל-OAuth ולוחצים על Back to dashboard.

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

    הגדרת מסך OAuth

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

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

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

  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. בחלונית הניווט של Xcode, בוחרים את הקובץ GoogleHomeAPISampleIOS כדי לערוך את הגדרות הפרויקט.

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

  2. לוחצים על הכרטיסייה כללי בחלק העליון ובוחרים את היעד GoogleHomeAPISampleIOS בצד ימין.

  3. גוללים למטה עד שמגיעים לקטע מסגרות, ספריות ותוכן מוטמע. שתי המסגרות של Home API אמורות להופיע ברשימה.

  4. בעמודה Embed, בוחרים באפשרות Embed & Sign עבור GoogleHomeSDK.xcframework. צריך להשאיר את המסגרת השנייה, GoogleHomeTypes.xcframework, כלא להטמיע.

  5. בתחתית הרשימה, לוחצים על הסמל +.

  6. כשמתבקשים, מחפשים את SafariServices.framework ולוחצים על הוספה. מוודאים שהעמודה Embed מוגדרת כ-Do Not Embed עבור הרשומה הזו.

    הטמעה וחתימה

  7. לוחצים על MatterAddDeviceExtension בקטע Target כדי לערוך את היעד.

  8. גוללים למטה עד שמגיעים לקטע Frameworks and Libraries. הערך GoogleHomeSDK.xcframework אמור להופיע ברשימה.

  9. בעמודה הטמעה, בוחרים באפשרות ללא הטמעה.

  10. מגדירים את מזהי הלקוח של המפתח ושל OAuth:

    1. בחלונית הניווט, מחפשים את התיקייה GoogleHomeAPISampleIOS ופותחים את הקובץ Info.plist לעריכה.

  11. בקובץ Info.plist, מאכלסים את השדה GIDClientID במזהה הלקוח של OAuth (ראו הקטע הגדרת הסכמה ל-OAuth) ואת השדה GIDTeamID במזהה צוות הפיתוח של Apple של חשבון הפיתוח ששימש בתהליך ההרשמה ל-OAuth.

  12. מגדירים את מערכת ה-build:

    הוספת דגלים לקישור

    1. בחלונית הניווט של Xcode, בוחרים את קובץ הפרויקט GoogleHomeAPISampleIOS כדי לערוך את הגדרות הפרויקט.
    2. לוחצים על הכרטיסייה Build Settings בחלק העליון ובוחרים את היעד GoogleHomeAPISampleIOS בצד ימין בקטע TARGETS.
    3. מחפשים את Other Linker Flags ומוסיפים שתי רשומות:
      • -lc++
      • -ObjC

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

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

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

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

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

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

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

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

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

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

    • GoogleHomeAPISampleIOS.swift כשערכת ה-SDK מופעלת.
    • RequestHandler.swift
    • CommissioningManager.swift