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

השתמש במדריך זה כדי לשלב את ה-SDK של הניווט ל-iOS באפליקציה ל-iOS.

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

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

חשוב: Places SDK ל-iOS, החל מגרסה 5.0, לא נכלל ב-API של הניווט ל-iOS וצריך להתקין אותו בנפרד. Google ממליצה להוריד ולהתקין את אותן הגרסאות של Places SDK ו-Navigation SDK. ראו התקנת Places SDK ל-iOS.

התקנת ה-SDK

מנהל חבילות Swift

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

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

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

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

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

1. מ-Xcode, עוברים אל 'קובץ > חבילות > עדכון לגרסאות האחרונות של החבילה'.
2. כדי לאמת את ההתקנה, עוברים לקטע תלויי חבילה ב-Project Navigator ומאמתים את החבילה והגרסה שלה.

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

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

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

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

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

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

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

CocoaPods

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

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

sudo gem install cocoapods

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

1. אם עדיין אין לך פרויקט ב-Xcode, צריך ליצור פרויקט עכשיו ולשמור אותו במחשב המקומי. אם אתם חדשים בפיתוח ל-iOS:
   1. יוצרים פרויקט חדש.
   2. בוחרים בתבנית iOS > אפליקציה.
   3. במסך האפשרויות של הפרויקט:
      1. מזינים את Project Name (שם הפרויקט).
      2. מתעדים את הערך בשדה מזהה חבילה. אפשר להשתמש בערך הזה כדי להגביל את מפתח ה-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, '14.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleNavigation', '5.3.1'
   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 עבור ה-SDK של הניווט ב-iOS ואת ה-SDK של מפות Google ל-iOS:

1. מורידים את קובצי ה-SDK הבינאריים ואת קובצי המשאבים הבאים:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. מפעילים את Xcode ופותחים פרויקט קיים או יוצרים פרויקט חדש. אם זו הפעם הראשונה שאתם משתמשים ב-iOS, תוכלו ליצור פרויקט חדש ולבחור באפשרות iOS App template (תבנית של אפליקציות ל-iOS).
3. מסירים מהפרויקט את כל ההפניות הקיימות במפות Google, בניווט ובמקומות.
   חשוב: Places SDK ל-iOS לא נכלל ב-Navigation SDK ל-iOS, וצריך להתקין אותו בנפרד. הדבר נכון לגבי גרסה 5.0 של Places SDK ל-iOS. Google ממליצה להוריד ולהתקין את אותן הגרסאות של Places SDK ל-iOS ושל הניווט ב-iOS. למידע נוסף, ראו התקנת Places SDK ל-iOS.
4. גוררים את ה-XCFrameworks הבאות לפרויקט בקטע Frameworks, ספריות ותוכן מוטמע כדי להתקין את ה-SDK של מפות ואת ה-SDK של ניווט (כשמוצגת הבקשה, בוחרים באפשרות העתקת פריטים לפי הצורך):
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
   • GoogleNavigation.xcframework
5. גוררים את הקובץ GoogleMaps.bundle מ-GoogleMapsResources שהורדתם לספרייה ברמה העליונה של פרויקט ה-Xcode. כשמופיעה בקשה, מוודאים שהאפשרות העתקת פריטים לפי הצורך מסומנת.
6. גוררים את GoogleNavigation.bundle מה-GoogleNavigationResources שהורדתם לספרייה ברמה העליונה של פרויקט ה-Xcode. כשמופיעה הודעה, מוודאים שהאפשרות העתקת פריטים לתיקייה של קבוצת היעד מסומנת.
7. בוחרים את הפרויקט מתוך Project Navigator, ובוחרים את יעד האפליקציה.
8. פותחים את הכרטיסייה יצירת שלבים, ובתוך קישור בינארי לספריות מוסיפים את המסגרות והספריות הבאות:
   • 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. ביעד של האפליקציה, לוחצים על הכרטיסייה יכולות, מפעילים את מצבי רקע ומפעילים את המצבים הבאים:
   • אודיו, AirPlay ו'תמונה בתוך תמונה'
   • עדכוני מיקום
10. בוחרים את הפרויקט ולא ביעד ספציפי, ופותחים את הכרטיסייה Build Settings (הגדרות build). בקטע Other Linker flags מוסיפים את ‑ObjC ל-debug ולהשקה. אם ההגדרות האלה לא מוצגות, משנים את המסנן בסרגל Build Settings (הגדרות Build) מ-Basic (בסיסי) ל-All (הכול).
11. פותחים את Info.plist ומוסיפים את צמדי המפתח/ערך הבאים:
    • מפתח: NSLocationWhenInUseUsageDescription (פרטיות – מיקום בעת השימוש בתיאור השימוש)
      ערך: "לאפליקציה זו נדרשת הרשאה להשתמש במיקום שלך לצורך ניווט במסלול מפורט".
    • מפתח: NSLocationAlwaysAndWhenInUseUsageDescription (פרטיות – מיקום תמיד ובזמן שימוש בתיאור השימוש)
      ערך: "לאפליקציה זו נדרשת הרשאה להשתמש במיקום שלך לצורך ניווט במסלול מפורט".

הוספת קובץ מניפסט הפרטיות של Apple

חשוב: ההוראות האלה לקובץ מניפסט הפרטיות של Apple חלות רק על גרסת ה-SDK האחרונה.

1. הורד את חבילת מניפסט הפרטיות עבור ה-SDK של הניווט ל-iOS: GoogleNavigationPrivacy.
2. צריך לחלץ את הקובץ כדי לגשת אל GoogleNavigationPrivacy.bundle.
3. מוסיפים את GoogleNavigationPrivacy.bundle ל-ניווט בפרויקט Xcode באמצעות אחת מהשיטות האלה. מוודאים שהתיבה 'הוספה ליעדים' מסומנת לגבי היעד של האפליקציה. לאחר ההוספה, הקובץ PrivacyInfo יופיע בסרגל הניווט בפרויקט ותוכלו לבדוק את הערכים.

4. מוודאים שמניפסט הפרטיות נוסף על ידי יצירת ארכיון של האפליקציה ויצירת דוח פרטיות מהארכיון.

הוספת מפתח 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"];

הוספת מפה

הקוד הזה מדגים איך להוסיף מפה פשוטה ל-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 הנכון.

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

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