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

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

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

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

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

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

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

מנהל חבילות Swift

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

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

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

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

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

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

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

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

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

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

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

כדי להסיר באופן ידני את ה-SDK של מפות Google ל-iOS:

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

CocoaPods

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

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

sudo gem install cocoapods

צור Podfile עבור ה-SDK של מפות Google ל-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 שלהם. הנה דוגמה שכוללת את התלות הנדרשת של ה-SDK של מפות Google ל-iOS:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '15.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '8.4.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 של מפות Google ל-iOS, ולקבוע את הגדרות ה-build ב-Xcode. XCFramework הוא חבילה בינארית שניתן להשתמש בה במספר פלטפורמות, כולל מכונות שמשתמשות בסיליקון של Apple.

1. מורידים את קובצי ה-SDK הבינאריים ואת קובצי המשאבים הבאים:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsM4B
   • GoogleMapsResources
2. צריך לחלץ את הקבצים כדי לגשת ל-XCFrameworks ולמשאבים.
3. אם עדיין אין לך פרויקט ב-Xcode, צריך ליצור פרויקט עכשיו ולשמור אותו במחשב המקומי. אם אתם חדשים בפיתוח ל-iOS:
   1. יוצרים פרויקט חדש.
   2. בוחרים בתבנית iOS > אפליקציה.
   3. במסך האפשרויות של הפרויקט:
      1. מזינים את Project Name (שם הפרויקט).
      2. מתעדים את הערך בשדה מזהה חבילה. אפשר להשתמש בערך הזה כדי להגביל את מפתח ה-API בהמשך.
      3. מגדירים את Interface של הפרויקט כ-Storyboard.
      4. מגדירים את Language כ-Swift או כ-Objective-C.
4. פותחים את הכרטיסייה כללי. גוררים את ה-XCFrameworks הבאות לפרויקט, בקטע Frameworks, ספריות ותוכן מוטמע. חשוב לבחור באפשרות לא להטמיע בכל XCFramework:
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
5. מעתיקים את GoogleMaps.bundle מה-GoogleMapsResources שהורדתם לספרייה ברמה העליונה של פרויקט ה-Xcode. צריך לבחור באפשרות העתקת פריטים לתיקייה של קבוצת היעד כשמתבקשים לעשות זאת.
6. בוחרים את הפרויקט מתוך Project Navigator, ובוחרים את יעד האפליקציה.
7. פותחים את הכרטיסייה Build שלבים (שלבי ה-build) ליעד של האפליקציה. ב-Link Binary with Libraries (קישור של Binary with Libraries) את המסגרות והספריות הבאות:
   • 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
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

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

9. כדי להתקין את Places SDK ל-iOS XCFramework, ראו תחילת העבודה עם Places SDK ל-iOS.

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

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

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

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

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

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

בדוגמאות הבאות, מחליפים את YOUR_API_KEY במפתח ה-API.

הערה: אם תיעדתם את מזהה החבילה של הפרויקט או אם קיבלתם אותו ממאפייני הפרויקט, תוכלו להשתמש בו כדי להגביל את מפתח ה-API לשימוש רק באפליקציות ל-iOS עם מזהה החבילה הספציפי הזה. ראו הגבלת מפתחות 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: הוספת מפה

Swift

/*
 *   Copyright 2020 Google Inc. All rights reserved.
 *
 *
 *   Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
 *   file except in compliance with the License. You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software distributed under
 *   the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 *   ANY KIND, either express or implied. See the License for the specific language governing
 *   permissions and limitations under the License.
 */

import UIKit
import GoogleMaps

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        // Create a GMSCameraPosition that tells the map to display the
        // coordinate -33.86,151.20 at zoom level 6.

        let options = GMSMapViewOptions()
        options.camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
        options.frame = self.view.bounds

        let mapView = GMSMapView(options: options)
        self.view.addSubview(mapView)

        // Creates a marker in the center of the map.
        let marker = GMSMarker()
        marker.position = CLLocationCoordinate2D(latitude: -33.86, longitude: 151.20)
        marker.title = "Sydney"
        marker.snippet = "Australia"
        marker.map = mapView
  }
}

Objective-C

/*
*   Copyright 2020 Google Inc. All rights reserved.
*
*
*   Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
*   file except in compliance with the License. You may obtain a copy of the License at
*
*   http://www.apache.org/licenses/LICENSE-2.0
*
*   Unless required by applicable law or agreed to in writing, software distributed under
*   the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
*   ANY KIND, either express or implied. See the License for the specific language governing
*   permissions and limitations under the License.
*/

#import "ViewController.h"
#import <GoogleMaps/GoogleMaps.h>

@interface ViewController()

@end

@implementation ViewController

-   (void)viewDidLoad {
  [super viewDidLoad];
  // Do any additional setup after loading the view.
  // Create a GMSCameraPosition that tells the map to display the
  // coordinate -33.86,151.20 at zoom level 6.
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
  options.frame = self.view.bounds;
  GMSMapView *mapView = [[GMSMapView alloc] initWithOptions:options];

  [self.view addSubview:mapView];

  // Creates a marker in the center of the map.
  GMSMarker *marker = [[GMSMarker alloc] init];
  marker.position = CLLocationCoordinate2DMake(-33.86, 151.20);
  marker.title = @"Sydney";
  marker.snippet = @"Australia";
  marker.map = mapView;
}

@end

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

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

כדי להצהיר על הסכימות של כתובות ה-URL שבהן נעשה שימוש ב-SDK של מפות Google ל-iOS, צריך להוסיף את השורות הבאות אל Info.plist:

LSApplicationQueriesSchemes googlechromes comgooglemaps

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

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

-canOpenURL: נכשלה עבור כתובת האתר: "comgooglemaps://" - שגיאה: "אפליקציה זו אינה מורשה לבצע שאילתות עבור סכימה comgooglemaps" -canOpenURL: נכשלה עבור כתובת האתר: "googlechromes://" - שגיאה: "האפליקציה הזו אינה מורשית לשלוח שאילתות עבור סכימה googlechromes"

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

מה עושים אחר כך

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

• דוגמאות לקוד
• מדריכים
  • הוספת מפה עם סמן
  • בחירת המקום הנוכחי והצגת הפרטים במפה
  • המרת קואורדינטות (geocoding)
• Codelabs
• פתרונות במפות Google