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

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

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

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

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

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

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

מנהל חבילות Swift

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

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

  1. פותחים את ה-Xcode project או את workspace, ואז עוברים אל 'קובץ' > 'הוספת יחסי תלות של חבילה'.
  2. מזינים את כתובת ה-URL בכתובת https://github.com/googlemaps/ios-places-sdk, הקישו על Enter כדי לצרף את החבילה ולוחצים על Add Package (הוספת חבילה).
  3. כדי להתקין version ספציפי, מגדירים את השדה כלל תלות לאחת מהאפשרויות שמבוססות על גרסה. בפרויקטים חדשים, מומלץ לציין את הגרסה העדכנית ביותר ולהשתמש באפשרות 'גרסה מדויקת'. בסיום, לוחצים על 'הוספת חבילה'.
  4. בחלון בחירת מוצרי חבילה, מוודאים שהשדה GooglePlaces יתווסף ליעד ה-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. כדי לאמת את ההתקנה, עוברים לקטע תלויי חבילה ב-Project Navigator ומאמתים את החבילה והגרסה שלה.

כדי להסיר יחסי תלות קיימים של Places SDK ל-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 מקומות קיימים ל-iOS, בצע את השלבים הבאים:
  1. בהגדרות של פרויקט Xcode, מאתרים את Frameworks, ספריות ותוכן מוטמע. משתמשים בסימן המינוס(-) כדי להסיר את המסגרת הבאה:
    • GooglePlaces.xcframework
  2. מהספרייה ברמה העליונה של פרויקט Xcode, מסירים את החבילה GooglePlaces.

CocoaPods

Places SDK ל-iOS זמין בתור pod של CocoaPod, GooglePlaces, שמכיל את כל היכולות של המקומות.

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

sudo gem install cocoapods

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

  1. אם עדיין אין לך פרויקט ב-Xcode, צריך ליצור פרויקט עכשיו ולשמור אותו במחשב המקומי. אם אתם מתחילים את הפיתוח ל-iOS, תוכלו ליצור פרויקט חדש ולבחור באפשרות iOS App template (תבנית של אפליקציות ל-iOS).
  2. יוצרים קובץ בשם Podfile בספריית הפרויקט. הקובץ הזה מגדיר את יחסי התלות של הפרויקט שלכם.
  3. עורכים את Podfile ומוסיפים את יחסי התלות יחד עם versions שלהן. הדוגמה הבאה מציינת את שם היעד של האפליקציה ואת השם של ה-pod GooglePlaces: 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GooglePlaces', '8.3.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.

התקנה ידנית

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

  1. מורידים את הקבצים הבינאריים וקובצי המשאבים של ה-SDK הבאים:
  2. צריך לחלץ את הקבצים כדי לגשת ל-XCFramework ולמשאבים.
  3. מפעילים את Xcode ופותחים פרויקט קיים או יוצרים פרויקט חדש. אם אתם מתחילים את הפיתוח ל-iOS, תוכלו ליצור פרויקט חדש ולבחור את תבנית האפליקציה ל-iOS.
  4. מסירים מהפרויקט חבילות של מפות Google מגרסאות קודמות.
  5. פותחים את הכרטיסייה 'כללי'. גוררים את ה-XCFramework הבא לפרויקט בקטע Frameworks, ספריות ותוכן מוטמע. חשוב לבחור באפשרות ללא הטמעה:
    • GooglePlaces.xcframework
    6. גוררים את GooglePlaces.bundle מ-GooglePlacesResources שהורדתם
  6. מעתיקים את GooglePlaces.bundle מה-GooglePlacesResources שהורדתם לספרייה ברמה העליונה של פרויקט ה-Xcode. צריך לבחור באפשרות העתקת פריטים לתיקייה של קבוצת היעד כשמתבקשים לעשות זאת.
  7. בוחרים את הפרויקט מתוך Project Navigator, ובוחרים את יעד האפליקציה.
  8. פותחים את הכרטיסייה שלבי ה-build. ב-Link Binary with Libraries (קישור Binary with Libraries) את מוסיפים את המסגרות והספריות הבאות:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework

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

GooglePlacesSwift

ניתן להתקין את ה-SDK של GooglePlacesSwift (Preview) באמצעות Swift Package Manager, CocoaPods ובאופן ידני. שלבי ההתקנה בכל התהליכים משקפים את השלבים המפורטים עבור Places SDK ל-iOS, עם ההבדלים הבאים:

  • חובה לציין Xcode 15.3.
  • עבור מנהל החבילות של Swift, צריך להחליף גם את המכונות GooglePlaces ב-GooglePlacesSwift. כולל הצהרות ייבוא.
  • מעדכנים את מספר הגרסה ל-0.1.0.
  • מחליפים את המכונות של https://github.com/googlemaps/ios-places-sdk ב-https://github.com/googlemaps/ios-places-swift-sdk.
  • אם מבצעים התקנה ידנית, צריך להוסיף את GooglePlacesSwift ה-XCFramework ואת קובצי המשאבים בנוסף ל-XCFramework ולקובצי המשאבים של GooglePlaces.

לדוגמה, אם משתמשים ב-CocoaPods, ה-Podfile הערוך יהיה: 

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.3'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GooglePlacesSwift', '0.1.0'
end

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

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

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

שלב 4: מוסיפים את מפתח ה-API לאפליקציה

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

Swift

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

  • מוסיפים את הצהרת הייבוא הבאה: 
    import GooglePlaces
  • מוסיפים את הפקודה הבאה ל-method application(_:didFinishLaunchingWithOptions:) ומחליפים את YOUR_API_KEY במפתח ה-API: 
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

  • מוסיפים את הצהרת הייבוא הבאה: 
    @import GooglePlaces;
  • מוסיפים את הפקודה הבאה ל-method application:didFinishLaunchingWithOptions: ומחליפים את YOUR_API_KEY במפתח ה-API: 
    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

GooglePlacesSwift

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

  • מוסיפים את הצהרת הייבוא הבאה: 
    import GooglePlacesSwift
  • מוסיפים את הפקודה הבאה ל-method application(_:didFinishLaunchingWithOptions:) ומחליפים את YOUR_API_KEY במפתח ה-API: 
    PlacesClient.shared.provideAPIKey("YOUR_API_KEY")

שלב 5: מתחילים לכתוב קוד

דוגמאות הקוד הבאות מדגימות איך להגיע למקום הנוכחי.

Swift

  import GooglePlaces
  import UIKit

  class GetStartedViewController : UIViewController {

    // Add a pair of UILabels in Interface Builder, and connect the outlets to these variables.
    @IBOutlet private var nameLabel: UILabel!
    @IBOutlet private var addressLabel: UILabel!

    private var placesClient: GMSPlacesClient!

    override func viewDidLoad() {
      super.viewDidLoad()
      placesClient = GMSPlacesClient.shared()
    }

    // Add a UIButton in Interface Builder, and connect the action to this function.
    @IBAction func getCurrentPlace(_ sender: UIButton) {
      let placeFields: GMSPlaceField = [.name, .formattedAddress]
      placesClient.findPlaceLikelihoodsFromCurrentLocation(withPlaceFields: placeFields) { [weak self] (placeLikelihoods, error) in
        guard let strongSelf = self else {
          return
        }

        guard error == nil else {
          print("Current place error: \(error?.localizedDescription ?? "")")
          return
        }

        guard let place = placeLikelihoods?.first?.place else {
          strongSelf.nameLabel.text = "No current place"
          strongSelf.addressLabel.text = ""
          return
        }

        strongSelf.nameLabel.text = place.name
        strongSelf.addressLabel.text = place.formattedAddress
      }
    }
  }

Objective-C

  #import "GetStartedViewController.h"
  @import GooglePlaces;

  @interface GetStartedViewController ()
  // Add a pair of UILabels in Interface Builder and connect the outlets to these variables
  @property (weak, nonatomic) IBOutlet UILabel *nameLabel;
  @property (weak, nonatomic) IBOutlet UILabel *addressLabel;
  @end

  @implementation GetStartedViewController {
    GMSPlacesClient *_placesClient;
  }

  - (void)viewDidLoad {
    [super viewDidLoad];
    _placesClient = [GMSPlacesClient sharedClient];
  }

  // Add a pair of UILabels in Interface Builder and connect the outlets to these variables.
  - (IBAction)getCurrentPlace:(UIButton *)sender {
    GMSPlaceField placeFields = (GMSPlaceFieldName | GMSPlaceFieldFormattedAddress);

    __weak typeof(self) weakSelf = self;
    [_placesClient findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:placeFields callback:^(NSArray<GMSPlaceLikelihood *> * _Nullable likelihoods, NSError * _Nullable error) {
      __typeof__(self) strongSelf = weakSelf;
      if (strongSelf == nil) {
        return;
      }

      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      }

      GMSPlace *place = likelihoods.firstObject.place;
      if (place == nil) {
        strongSelf.nameLabel.text = @"No current place";
        strongSelf.addressLabel.text = @"";
        return;
      }

      strongSelf.nameLabel.text = place.name;
      strongSelf.addressLabel.text = place.formattedAddress;
    }];
  }

  @end

GooglePlacesSwift

  struct ContentView: View {
    @State var place: Place?

    var body: some View {
      Button("Get Place") {
        // A hotel in Saigon with an attribution.
        let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
        let fetchPlaceRequest = FetchPlaceRequest(
          placeID: placeID,
          placeProperties: [.displayName, .formattedAddress]
        )
        Task {
          switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
          case .success(let place):
            self.place = place
          case .failure(let placesError):
            // Handle error
        }
      Text(swiftPlace?.displayName ?? "No place yet")
        .padding()
      Text(swiftPlace?.formattedAddress ?? "No place yet")
        .padding()
    }
  }

השלבים הבאים

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