הגדרת פרויקט ב-Xcode

אחרי שמפעילים את החיוב ויוצרים מפתח API, אפשר להגדיר את הפרויקט ב-Xcode שבו משתמשים לפיתוח האפליקציה.

נתוני הגרסה זמינים לכל גרסה.

שלב 1: מתקינים את התוכנה הנדרשת

כדי ליצור פרויקט באמצעות SDK של מפות ל-iOS, צריך להוריד ולהתקין את:

  • Xcode גרסה 15.0 ואילך

שלב 2: יוצרים את הפרויקט ב-Xcode ומתקינים את ה-SDK של מפות ל-iOS

Swift Package Manager

אפשר להתקין את ה-SDK של מפות ל-iOS באמצעות Package Manager של Swift. כדי להוסיף את ה-SDK, צריך לוודא שהסרתם את כל יחסי התלות הקיימים של SDK של מפות ל-iOS.

כדי להוסיף את ה-SDK לפרויקט חדש או קיים:

  1. פותחים את Xcode project או workspace, ואז עוברים אל קובץ > הוספת יחסי תלות בחבילות.
  2. מזינים את כתובת ה-URL https://github.com/googlemaps/ios-maps-sdk, מקישים על Enter כדי לשלוח את החבילה ולוחצים על 'הוספת חבילה'.
  3. כדי להתקין version ספציפי, מגדירים את השדה Dependency Rule לאחת מהאפשרויות שמבוססות על גרסה. בפרויקטים חדשים, מומלץ לציין את הגרסה האחרונה ולהשתמש באפשרות 'גרסה מדויקת'. בסיום, לוחצים על 'הוספת חבילה'.

כדי לעדכן את package בפרויקט קיים, פועלים לפי השלבים הבאים:

  1. אם משדרגים מגרסה מוקדמת יותר מ-9.0.0, צריך להסיר את יחסי התלות הבאים אחרי השדרוג: GoogleMapsBase,‏ GoogleMapsCore ו-GoogleMapsM4B. אין להסיר את התלות ב-GoogleMaps. מידע נוסף זמין בהערות המוצר של גרסה 9.0.0.

    בהגדרות הפרויקט ב-Xcode, מחפשים את האפשרות Frameworks, Libraries, and Embedded Content. משתמשים בסימן המינוס(-) כדי להסיר את המסגרת הבאה:

    • GoogleMapsBase (רק לשדרוגים מגרסאות מוקדמות יותר מ-9.0.0)
    • GoogleMapsCore (רק לשדרוגים מגרסאות מוקדמות יותר מ-9.0.0)
    • GoogleMapsM4B (רק לשדרוגים מגרסאות מוקדמות יותר מ-9.0.0)
  2. ב-Xcode, עוברים אל 'קובץ' > 'חבילות' > 'עדכון לגרסאות החבילות העדכניות ביותר'.
  3. כדי לאמת את ההתקנה, עוברים לקטע Package Dependencies ב-Project Navigator כדי לאמת את החבילה ואת הגרסה שלה.

כדי להסיר יחסי תלות קיימים של SDK של מפות ל-iOS שנוספו באמצעות CocoaPods:

  1. סוגרים את סביבת העבודה ב-Xcode. פותחים את הטרמינל ומריצים את הפקודה הבאה: 
    sudo gem install cocoapods-deintegrate cocoapods-clean 
pod deintegrate 
pod cache clean --all
  2. אם אתם לא משתמשים ב-Podfile, ב-Podfile.resolved וב-workspace של Xcode למטרה אחרת מלבד CocoaPods, כדאי להסיר אותם.

כדי להסיר את ה-SDK של מפות ל-iOS שמותקן באופן ידני:
  1. בהגדרות הפרויקט ב-Xcode, מחפשים את האפשרות Frameworks, Libraries, and Embedded Content. משתמשים בסימן המינוס(-) כדי להסיר את המסגרת הבאה:
    • GoogleMaps
    • GoogleMapsBase (רק להתקנות ישנות יותר מגרסה 9.2.0)
    • GoogleMapsCore (רק להתקנות ישנות יותר מגרסה 9.2.0)
    • GoogleMapsM4B (רק להתקנות ישנות יותר מגרסה 9.0.0)
  2. מסירים את החבילה GoogleMaps מהספרייה ברמה העליונה של פרויקט Xcode.

התקנה ידנית

במדריך הזה מוסבר איך להוסיף ידנית לפרויקט את ה-XCFrameworks שמכילים את Maps SDK ל-iOS, ולהגדיר את הגדרות ה-build ב-Xcode. XCFramework הוא חבילת קבצים בינאריים שאפשר להשתמש בה בכמה פלטפורמות, כולל במכונות עם Apple silicon.

  1. מורידים את קובצי ה-SDK הבינאריים ואת קובצי המשאבים הבאים:
  2. מחלצים את הקבצים כדי לגשת ל-XCFrameworks ולמשאבים.
  3. אם עדיין אין לכם פרויקט Xcode, אתם יכולים ליצור אחד עכשיו ולשמור אותו במחשב המקומי. אם אתם מפתחים חדשים ב-iOS:
    1. יוצרים פרויקט חדש.
    2. בוחרים את התבנית iOS‏ > App.
    3. במסך האפשרויות של הפרויקט:
      1. מזינים את שם הפרויקט.
      2. מתעדים את הערך בשדה מזהה החבילה. אפשר להשתמש בערך הזה כדי להגביל את מפתח ה-API בהמשך.
      3. מגדירים את ממשק הפרויקט ל-Storyboard.
      4. מגדירים את Language (שפה) ל-Swift או ל-Objective-C.
  4. פותחים את הכרטיסייה כללי. גוררים את ה-XCFramework הבא לפרויקט בקטע Frameworks, Libraries, and Embedded Content. חשוב לבחור באפשרות לא להטמיע:
    • GoogleMaps.xcframework
  5. מעתיקים את GoogleMaps.bundle מהספרייה GoogleMapsResources שהורדת לספרייה ברמה העליונה של פרויקט Xcode. חשוב לבחור באפשרות העתקת פריטים לתיקייה של קבוצת היעד כשמופיעה ההודעה.
  6. בוחרים את הפרויקט מ-Project Navigator ובוחרים את היעד של האפליקציה.
  7. פותחים את הכרטיסייה Build Phases של היעד של האפליקציה. בקטע קישור בין קובץ הבינארי לספריות, מוסיפים את המסגרות והספריות הבאות:
    • Accelerate.framework
    • Contacts.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libz.tbd
    • Metal.framework
    • OpenGLES.framework (רק אם משתמשים ב-OpenGL)
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

  8. בוחרים את הפרויקט ולא יעד ספציפי, ופותחים את הכרטיסייה Build Settings. בקטע Linking - General -> Other Linker Flags, מוסיפים את הערך -ObjC לאפשרויות Debug ו-Release. אם ההגדרות האלה לא מוצגות, משנים את הסינון בסרגל Build Settings מ-Basic ל-All.

  9. במאמר תחילת העבודה עם Places SDK ל-iOS מוסבר איך להתקין את XCFramework של Places SDK ל-iOS.

CocoaPods

ה-SDK של מפות ל-iOS זמין כ-pod של CocoaPods. CocoaPods הוא מנהל יחסי תלות בקוד פתוח לפרויקטים של Cocoa ב-Swift וב-Objective-C.

אם עדיין לא התקנתם את הכלי CocoaPods, תוכלו להתקין אותו ב-macOS על ידי הפעלת הפקודה הבאה מהטרמינל. לפרטים נוספים, ראו מדריך למתחילים ב-CocoaPods.

sudo gem install cocoapods

יוצרים Podfile ל-SDK של מפות ל-iOS ומשתמשים בו כדי להתקין את ה-API ואת יחסי התלות שלו:

  1. אם עדיין אין לכם פרויקט Xcode, אתם יכולים ליצור אחד עכשיו ולשמור אותו במחשב המקומי. אם אתם מפתחים חדשים ב-iOS:
    1. יוצרים פרויקט חדש.
    2. בוחרים את התבנית iOS‏ > App.
    3. במסך האפשרויות של הפרויקט:
      1. מזינים את שם הפרויקט.
      2. מתעדים את הערך בשדה מזהה החבילה. אפשר להשתמש בערך הזה כדי להגביל את מפתח ה-API בהמשך.
      3. מגדירים את ממשק הפרויקט ל-Storyboard.
      4. מגדירים את Language (שפה) ל-Swift או ל-Objective-C.
  2. יוצרים קובץ בשם Podfile בספריית הפרויקט. הקובץ הזה מגדיר את יחסי התלות של הפרויקט.
  3. עורכים את הקובץ Podfile ומוסיפים את יחסי התלות יחד עם הגרסאות שלהם. הנה דוגמה שכוללת את התלות שדרושה ל-Maps SDK ל-iOS: 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GoogleMaps', '9.2.0'
end
    חשוב להריץ את pod outdated באופן קבוע כדי לזהות אם יש גרסה חדשה יותר, וכך לוודא שאתם תמיד משתמשים בגרסה העדכנית ביותר. אם צריך, משדרגים לגרסה האחרונה.
  4. שומרים את ה-Podfile.

  5. פותחים מסוף ועוברים לספרייה שמכילה את Podfile:

    cd <path-to-project>

  6. מריצים את הפקודה pod install. הפקודה הזו תתקין את ממשקי ה-API שצוינו ב-Podfile, יחד עם יחסי התלות שלהם.

    pod install

  7. סוגרים את Xcode ופותחים (לחיצה כפולה) את הקובץ .xcworkspace של הפרויקט כדי להפעיל את Xcode. מעכשיו והלאה, עליכם להשתמש בקובץ .xcworkspace כדי לפתוח את הפרויקט.

כדי לעדכן את ה-API של פרויקט קיים:

  1. פותחים מסוף ועוברים לספריית הפרויקט שמכילה את Podfile.
  2. מריצים את הפקודה pod update. הפעולה הזו תעדכן את כל ממשקי ה-API שצוינו ב-Podfile לגרסה האחרונה.

שלב 3: מוסיפים את מפתח ה-API לפרויקט

בקטע קבלת מפתח API יצרתם מפתח API לאפליקציה. עכשיו צריך להוסיף את המפתח הזה לפרויקט ב-Xcode.

בדוגמאות הבאות, מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם.

Swift

מוסיפים את מפתח ה-API ל-AppDelegate.swift באופן הבא:

  1. מוסיפים את הצהרת הייבוא הבאה: 
    import GoogleMaps
  2. מוסיפים את הקוד הבא ל-method‏ application(_:didFinishLaunchingWithOptions:), באמצעות מפתח ה-API: 
    GMSServices.provideAPIKey("YOUR_API_KEY")
  3. אם אתם משתמשים גם ב-Places API, צריך להוסיף את המפתח שוב כפי שמתואר כאן: 
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

מוסיפים את מפתח ה-API ל-AppDelegate.m באופן הבא:

  1. מוסיפים את הצהרת הייבוא הבאה: 
    @import GoogleMaps;
  2. מוסיפים את הקוד הבא ל-method‏ application:didFinishLaunchingWithOptions:, באמצעות מפתח ה-API: 
    [GMSServices provideAPIKey:@"YOUR_API_KEY"];
  3. אם אתם משתמשים גם ב-Places API, צריך להוסיף את המפתח שוב כפי שמתואר כאן: 
    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

שלב 4 (אופציונלי): בודקים את קובץ Privacy Manifest של Apple

Apple דורשת פרטי פרטיות של אפליקציות שמוצגות ב-App Store. מידע נוסף ועדכונים זמינים בדף 'פרטים על פרטיות האפליקציה' ב-App Store של Apple.

קובץ המניפסט של Apple לפרטיות נכלל בחבילת המשאבים של ה-SDK. כדי לוודא שקובץ המניפסט של הפרטיות נכלל ולבדוק את התוכן שלו, יוצרים ארכיון של האפליקציה ויוצרים דוח פרטיות מהארכיון.

שלב 5 (אופציונלי): הכרזה על סכימות כתובות ה-URL שבהן ה-API משתמש

החל מ-iOS 9 ו-Xcode 7, אפליקציות יכולות להצהיר על הסכמות כתובות ה-URL שהן מתכוונות לפתוח, על ידי ציון הסכמות בקובץ Info.plist של האפליקציה. כשמשתמש לוחץ על הלוגו של Google במפה, ערכת ה-SDK של מפות Google ל-iOS פותחת את אפליקציית מפות Google לנייד, וכך האפליקציה יכולה להצהיר על סכמות כתובות ה-URL הרלוונטיות.

כדי להצהיר על סכמות כתובות ה-URL שבהן משתמש ה-SDK של מפות ל-iOS, מוסיפים את השורות הבאות לקובץ Info.plist:

 <key>LSApplicationQueriesSchemes</key>
 <array>
        <string>googlechromes</string>
        <string>comgooglemaps</string>
    </array>

בצילום המסך הבא מוצגת ההגדרה בממשק המשתמש של Xcode:

הגדרת LSApplicationQueriesSchemes ב-Xcode

בלי ההצהרה שלמעלה, יכולות להתרחש השגיאות הבאות כשהמשתמש מקייש על הלוגו של Google במפה:

  • -canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
  • -canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

כדי למנוע את השגיאות האלה, צריך להוסיף את ההצהרה לקובץ Info.plist.

המאמרים הבאים

עכשיו, אחרי שיצרתם מפתח API ופרויקט Xcode, אתם יכולים ליצור אפליקציות ולהריץ אותן. ב-Navigation SDK ל-iOS יש הרבה מדריכים ואפליקציות לדוגמה שיעזרו לכם להתחיל. פרטים נוספים זמינים במאמרים הבאים: