הגדרת הפרויקט

מדריך זה מסביר איך לשלב את Navigation SDK ל-iOS באפליקציה ל-iOS.

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

• כדי להתחיל להשתמש ב-Navigation SDK ל-iOS, צריך שיהיה לכם פרויקט עם חשבון לחיוב ו-Maps SDK ל-iOS מופעל. מומלץ ליצור כמה בעלים של פרויקט ואדמינים לענייני חיוב, כדי שתמיד יהיה מישהו עם התפקידים האלה שזמין לצוות. מידע נוסף זמין במאמר הגדרת הפרויקט ב-Google Cloud.
• כדי לבנות פרויקט באמצעות Navigation SDK ל-iOS, צריך גרסה 15.0 ואילך של Xcode.
• גרסת היעד המינימלית של iOS ל-SDK לניווט היא 15.0.

שלב 1: מתקינים את ה-SDK

מנהל חבילות SWIFT

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

חשוב: ההוראות האלה מבוססות על ההנחה שנעשה שימוש ב-Xcode מגרסה 15 ואילך, אבל הן צריכות להיות דומות לגרסאות קודמות של Xcode.

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

1. פותחים את ה-Xcode project או workspace ועוברים אל 'קובץ' > 'הוספת יחסי תלות של חבילה'.
2. מזינים https://github.com/googlemaps/ios-navigation-sdk בתור כתובת ה-URL, מקישים על Enter כדי למשוך את החבילה ולוחצים על 'Add Package'.
3. כדי להתקין version ספציפי, צריך להגדיר את השדה כלל תלות לאחת מהאפשרויות שמבוססות על גרסה. בפרויקטים חדשים, מומלץ לציין את הגרסה האחרונה ולהשתמש באפשרות 'גרסה מדויקת'. בסיום, לוחצים על 'הוספת חבילה'.
4. בחלון Choose Package Products, מוודאים שהערך של GoogleNavigation יתווסף ליעד main שציינתם. בסיום, לוחצים על 'הוספת חבילה'.
5. כדי לבדוק את ההתקנה, צריך לעבור לחלונית General של היעד. ב-Frameworks, ספריות ותוכן מוטמע אתם אמורים לראות את החבילות המותקנות. אפשר גם לעיין בקטע 'יחסי תלות של חבילה' בדף 'Project Navigator' כדי לאמת את החבילה ואת הגרסה שלה.

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

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

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

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

חשוב: לפעמים לא ניתן לפתור פריטי מידע שנוצרו בתהליך הפיתוח (Artifact) או שעלולות להתרחש שגיאות. במקרה כזה, בוחרים באפשרות 'קובץ > חבילות' > 'איפוס מטמון החבילה'.

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

1. סוגרים את סביבת העבודה של Xcode. פותחים את הטרמינל ומריצים את הפקודה הבאה:

   sudo gem install cocoapods-deintegrate cocoapods-clean 
   pod deintegrate 
   pod cache clean --all

2. מסירים את Podfile, Podfile.resolved ואת ה-Xcode workspace אם אתם לא משתמשים בהם לכל מטרה אחרת מלבד CocoaPods.

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

1. בהגדרות האישיות של פרויקט Xcode, מחפשים את Frameworks, ספריות ותוכן מוטמע. משתמשים בסימן המינוס(-) כדי להסיר את המסגרת הבאה:
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
   • GoogleNavigation.xcframework
2. מהספרייה ברמה העליונה של פרויקט Xcode, מסירים את החבילה GoogleMaps.

CocoaPods

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

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

sudo gem install cocoapods

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

1. אם עדיין לא יצרת פרויקט Xcode, עליך ליצור פרויקט עכשיו ולשמור אותו במחשב המקומי. אם זו הפעם הראשונה שאתם משתמשים בפיתוח ל-iOS:
   1. יוצרים פרויקט חדש.
   2. בוחרים את התבנית iOS > אפליקציה.
   3. במסך אפשרויות הפרויקט:
      1. מזינים את Project Name (שם הפרויקט).
      2. מתעדים את הערך בשדה Bundle ID (מזהה החבילה). אפשר להשתמש בערך הזה כדי להגביל את מפתח ה-API בהמשך.
      3. מגדירים את הפרויקט Interface כ-Storyboard.
      4. מגדירים את Language כ-Swift או Objective-C.
2. יוצרים קובץ בשם Podfile בספריית הפרויקט. הקובץ הזה מגדיר את יחסי התלות של הפרויקט.
3. עורכים את Podfile ומוסיפים את יחסי התלות עם versions שלהם. הנה דוגמה שכוללת את התלות הדרושה עבור Navigation SDK עבור iOS: # הפניה להתקנות של Cocoapods מספר

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '15.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleNavigation', '9.0.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 לגרסה האחרונה.

התקנה ידנית

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

יש לבצע את השלבים הבאים כדי להתקין את XCFrameworks ל-Navigation SDK ל-iOS, ואת ה-SDK של מפות ל-iOS:

1. מורידים את הקבצים הבינאריים וקובצי המשאבים הבאים של ה-SDK:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. מפעילים את Xcode ופותחים פרויקט קיים או יוצרים פרויקט חדש. אם זו הפעם הראשונה שאתם משתמשים ב-iOS, צריך ליצור פרויקט חדש ולבחור את התבנית ל-iOS App template.
3. מסירים מהפרויקט את כל ההפניות הקיימות ל'מפות', 'ניווט' ו'מקומות'.
   חשוב: ה-Place SDK ל-iOS לא כלול ב-Navigation SDK ל-iOS, וצריך להתקין אותו בנפרד. הדבר נכון לגרסה 5.0 של Places SDK ל-iOS. Google ממליצה להוריד ולהתקין את אותן גרסאות של Places SDK ל-iOS ושל Navigation SDK ל-iOS. למידע נוסף, אפשר לקרוא את המאמר התקנת Places SDK ל-iOS.
4. גוררים את ה-XCFrameworks הבאות לפרויקט בקטע Frameworks, ספריות ותוכן מוטמע כדי להתקין את ערכות ה-SDK של מפות Google וגם את ערכות ה-SDK לניווט (כשמוצגת בקשה, בוחרים באפשרות העתקת פריטים במידת הצורך):
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
   • GoogleNavigation.xcframework
5. גוררים את הקובץ GoogleMaps.bundle מ-GoogleMapsResources שהורדתם לספרייה ברמה העליונה של פרויקט ה-Xcode. כשמופיעה בקשה, מוודאים שהאפשרות העתקת פריטים במקרה הצורך מסומנת.
6. גוררים את הקובץ GoogleNavigation.bundle מ-GoogleNavigationResources שהורדתם לספרייה ברמה העליונה של פרויקט ה-Xcode. כשמופיעה הבקשה, מוודאים שהאפשרות העתקת הפריטים לתיקייה של קבוצת היעד מסומנת.
7. בוחרים את הפרויקט מ-Project Navigator ובוחרים את יעד האפליקציה.
8. פותחים את הכרטיסייה Build Phases (שלבי ה-build) ובתוך Link Binary with Libraries (קישור Binary with Libraries) מוסיפים את ה-frameworks ואת הספריות הבאות:
   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libxml2.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework
   • UserNotifications.framework
   • WebKit.framework
9. ביעד של האפליקציה, בוחרים בכרטיסייה Capabilities, מפעילים את Background Modes ומפעילים את המצבים הבאים:
   • אודיו, AirPlay ו'תמונה בתוך תמונה'
   • עדכוני מיקום
10. בוחרים את הפרויקט ולא יעד ספציפי ופותחים את הכרטיסייה Build Settings. בקטע Other Linker Banners (סימון לקישור אחר), מוסיפים את ‑ObjC גם לניפוי באגים וגם לגרסה. אם ההגדרות האלה לא מוצגות, משנים את המסנן בסרגל הגדרות Build מבסיסי להכול.
11. פותחים את Info.plist ומוסיפים את צמדי המפתח/ערך הבאים:
    • מפתח: NSLocationWhenInUseUsageDescription (פרטיות – מיקום בזמן השימוש בתיאור השימוש)
      ערך: "האפליקציה הזו צריכה הרשאה להשתמש במיקום שלך כדי לקבל מסלול מפורט".
    • מפתח: NSLocationAlwaysAndWhenInUseUsageDescription (פרטיות – מיקום תמיד ותיאור בזמן שימוש)
      ערך: "לאפליקציה הזו נדרשת הרשאה להשתמש במיקום שלך לקבלת מסלול מפורט".

שלב 2: בודקים את קובץ מניפסט הפרטיות של Apple

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

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

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

הדוגמאות הבאות מראות איך להוסיף את מפתח ה-API לפרויקט ב-Xcode:

Swift

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

1. מוסיפים את הצהרות הייבוא הבאות:

   import GoogleMaps
   import GoogleNavigation

2. מוסיפים את הטקסט הבא ל-method application(_:didFinishLaunchingWithOptions:):

   GMSServices.provideAPIKey("YOUR_API_KEY")

Objective-C

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

1. מוסיפים את הצהרות הייבוא הבאות:

   @import GoogleMaps;
   @import GoogleNavigation;

2. מוסיפים את הטקסט הבא ל-method application:didFinishLaunchingWithOptions::

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

שלב 4: הוספת מפה

הקוד הזה מדגים איך להוסיף מפה פשוטה ל-ViewController קיים, כולל כמה הגדרות ראשוניות לניווט.

כדי להפעיל את הניווט, המשתמש צריך להסכים לתנאים ולהגבלות. כדי לשלוח הודעה למשתמש, צריך להתקשר ל-GMSNavigationServices.showTermsAndConditionsDialogIfNeeded() ולבדוק אם התנאים אושרו. אם המשתמש דחה את התנאים, ל-mapView.isNavigationEnabled = true אין השפעה, ו-mapView.navigator הוא אפס.

Swift

import UIKit
import GoogleNavigation

class ViewController: UIViewController {

  var mapView: GMSMapView!
  var locationManager: CLLocationManager!

  override func loadView() {
    locationManager = CLLocationManager()
    locationManager.requestAlwaysAuthorization()

    let camera = GMSCameraPosition.camera(withLatitude: 47.67, longitude: -122.20, zoom: 14)
    mapView = GMSMapView.map(withFrame: CGRect.zero, camera: camera)

    // Show the terms and conditions.
    let companyName = "Ride Sharing Co."
    GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
      withCompanyName: companyName) { termsAccepted in
      if termsAccepted {
        // Enable navigation if the user accepts the terms.
        self.mapView.isNavigationEnabled = true
      } else {
        // Handle the case when the user rejects the terms and conditions.
      }
    }

    view = mapView
  }

  // TODO: Add navigation code.

}

Objective-C

#import "ViewController.h"
@import GoogleNavigation;

@interface ViewController ()
@end

@implementation ViewController
GMSMapView *_mapView;
CLLocationManager *_locationManager;

-   (void)loadView {

  _locationManager = [[CLLocationManager alloc] init];
  [_locationManager requestAlwaysAuthorization];

  GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:47.67
                                                          longitude:-122.20
                                                               zoom:14];
  _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];

  // Show the terms and conditions.
  NSString *companyName = @"Ride Sharing Co.";
  [GMSNavigationServices
    showTermsAndConditionsDialogIfNeededWithCompanyName:companyName
    callback:^(BOOL termsAccepted) {
     if (termsAccepted) {
       // Enable navigation if the user accepts the terms.
       _mapView.navigationEnabled = YES;
     } else {
       // Handle the case when the user rejects the terms and conditions.
     }
   }];

  self.view = _mapView;
}

// TODO: Add navigation code.

@end

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

אם אתם לקוחות של שירותי ניידות

אם אתם לקוחות של שירותי ניידות, תוכלו לקרוא על חיוב במסמכי התיעוד בנושא Mobility. מידע נוסף על תיעוד טרנזקציות זמין במאמר הגדרת חיוב. במאמר שיוך השימוש בשירות לטרנזקציות ניידות מוסבר איך מוסיפים מזהי טרנזקציות להטמעה של Navigation SDK.