إعداد مشروع Xcode

مدير حزم Swift

يمكن تثبيت حزمة تطوير برامج الأماكن لأجهزة iOS من خلال أداة Swift Package Manager. لإضافة حزمة تطوير البرامج (SDK)، تأكّد من إزالة أي حزمة SDK حالية للأماكن لتبعيات iOS.

لإضافة حزمة تطوير البرامج (SDK) إلى مشروع جديد أو حالي، اتّبِع الخطوات التالية:

1. افتح تطبيق Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة تبعيات الحزمة.
2. أدخِل https://github.com/googlemaps/ios-places-sdk كعنوان URL، واضغط على Enter لسحب الحزمة، ثم انقر على "إضافة حزمة".
3. لتثبيت علامة version محدّدة، اضبط حقل قاعدة التبعية على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصح بتحديد أحدث إصدار واستخدام خيار "النسخة المحددة". بعد اكتمال عملية النقل، انقر على "إضافة حزمة".
4. من نافذة اختيار منتجات الحزمة، تأكَّد من إضافة GooglePlaces إلى هدف main المحدَّد. بعد اكتمال عملية النقل، انقر على "إضافة حزمة".
5. للتحقّق من عملية التثبيت، انتقِل إلى جزء General في استهدافك. من المفترَض أن تظهر الحِزَم المثبَّتة في أُطر العمل والمكتبات والمحتوى المضمَّن. يمكنك أيضًا الاطّلاع على قسم "تبعيات الحِزم" ضمن Project Navigator (أداة التنقّل في المشروع) للتحقّق من الحزمة وإصدارها.

لتعديل package لمشروع حالي، اتّبِع الخطوات التالية:

1. في حال الترقية من إصدار أقدم من 9.0.0، عليك إزالة الاعتماديات التالية: GoogleMapsBase وGoogleMapsCore وGoogleMapsM4B بعد الترقية. يجب عدم إزالة تبعية GoogleMaps. لمعرفة مزيد من المعلومات، يمكنك الاطّلاع على ملاحظات الإصدار 9.0.0.

   من إعدادات ضبط مشروع Xcode، ابحث عن الإطارات والمكتبات والمحتوى المضمَّن. استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:

   • GoogleMapsBase (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
   • GoogleMapsCore (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
   • GoogleMapsM4B (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
2. من Xcode، انتقِل إلى "ملف" > "الحِزم" > "تحديث إلى أحدث إصدارات الحزمة".
3. للتحقّق من عملية التثبيت، انتقِل إلى القسم تبعيات الحزمة في Project Navigator (أداة التنقّل في المشروع) للتحقّق من الحزمة وإصدارها.

لإزالة حزمة تطوير البرامج (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.

1. من إعدادات ضبط مشروع Xcode، ابحث عن الإطارات والمكتبات والمحتوى المضمَّن. استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:
   • GooglePlaces.xcframework
2. من دليل المستوى الأعلى لمشروع Xcode، أزِل الحزمة GooglePlaces.

CocoaPods

تتوفر حزمة تطوير برامج الأماكن لأجهزة iOS في شكل مجموعة CocoaPod، اسمها GooglePlaces، والتي تحتوي على جميع إمكانيات الأماكن.

CocoaPods هو مدير تبعية مفتوح المصدر لمشاريع Swift وObjective-C Cocoa. إذا لم تكن أداة CocoaPods متوفّرة لديك، يمكنك تثبيتها على نظام التشغيل macOS من خلال تنفيذ الأمر التالي من الوحدة الطرفية. لمعرفة التفاصيل، يمكنك الاطّلاع على دليل بدء استخدام CocoaPods.

sudo gem install cocoapods

أنشئ Podfile لحزمة تطوير برامج "الأماكن" لأجهزة iOS واستخدِمها لتثبيت حزمة SDK وتبعياتها:

1. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على جهازك المحلي. إذا كنت حديث العهد بتطوير نظام iOS، أنشِئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
2. أنشئ ملفًا باسم "Podfile" في دليل مشروعك. يحدد هذا الملف تبعيات مشروعك.
3. يمكنك تعديل Podfile وإضافة الموارد التابعة لك إلى جانب إصداراتها. في ما يلي مثال يحدّد اسم استهداف التطبيق واسم مجموعة 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. سيؤدي هذا الإجراء إلى تثبيت واجهات برمجة التطبيقات المحدّدة في Podfile، بالإضافة إلى أي ملحقات قد تكون مرتبطة بها.

   pod install

7. أغلِق Xcode، ثم افتح ملف .xcworkspace الخاص بمشروعك (بالنقر مرّتين) لتشغيل Xcode. ومن الآن فصاعدًا، عليك استخدام ملف .xcworkspace لفتح المشروع.

لتحديث واجهة برمجة التطبيقات لمشروع حالي، اتّبِع الخطوات التالية:

1. افتح نافذة طرفية وانتقِل إلى دليل المشروع الذي يحتوي على Podfile.
2. شغِّل الأمر pod update. سيؤدي هذا الإجراء إلى تحديث جميع واجهات برمجة التطبيقات المحدّدة في Podfile إلى أحدث إصدار.

التثبيت اليدوي

يوضّح هذا الدليل كيفية إضافة XCFramework يدويًا إلى مشروعك في حزمة Places SDK لنظام التشغيل iOS، وضبط إعدادات تصميمك في Xcode. XCFramework هو حزمة ثنائية يمكنك استخدامها على عدة أنظمة أساسية، بما في ذلك الأجهزة التي تستخدم Apple silicon.

1. نزِّل البرنامج الثنائي لحزمة تطوير البرامج (SDK) وملفات الموارد التالية:
   • GooglePlaces
   • GooglePlacesResources
2. يمكنك استخراج الملفات للوصول إلى XCFramework والموارد.
3. شغِّل Xcode وافتح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا. إذا كنت حديث العهد بتطوير نظام iOS، أنشِئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
4. يجب إزالة أي حِزم في "خرائط Google" من الإصدارات السابقة من مشروعك.
5. افتح علامة التبويب "إعدادات عامة". اسحب إطار عمل XCFrame التالي إلى مشروعك ضمن Frameworks (المكتبات) و"المحتوى المضمَّن". تأكّد من اختيار عدم التضمين:
   • GooglePlaces.xcframework
اسحب GooglePlaces.bundle من GooglePlacesResources الذي نزّلته
6. انسخ GooglePlaces.bundle من GooglePlacesResources الذي نزّلته في دليل المستوى الأعلى لمشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.
7. اختَر مشروعك من Project Navigator، ثم اختَر الهدف الذي يستهدفه تطبيقك.
8. افتح علامة التبويب مراحل التصميم. ضمن ربط النظام الثنائي بالمكتبات، أضِف أُطر العمل والمكتبات التالية:
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

9. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات التصميم. في القسم الربط - عام -> علامات الروابط الأخرى، أضِف -ObjC إلى "تصحيح الأخطاء" و "الإصدار". إذا لم تكن هذه الإعدادات مرئية، غيِّر الفلتر في شريط إعدادات التصميم من أساسي إلى الكل.

GooglePlacesSwift

يمكنك تثبيت حزمة تطوير البرامج (SDK) GooglePlacesSwift (المعاينة) باستخدام Swift Package Manager وCocoaPods ويدويًا. إنّ خطوات التثبيت في جميع العمليات تعكس الخطوات الموضّحة في حِزم SDK لـ "الأماكن" لأجهزة iOS، مع الاختلافات التالية:

• يجب إدخال Xcode 15.3.
• في حال استخدام "إدارة الحِزم" في Swift، يجب استبدال مثيلات GooglePlaces بـ GooglePlacesSwift. ويتضمن هذا عبارات الاستيراد.
  • استبدِل https://github.com/googlemaps/ios-places-sdk بمثيل https://github.com/googlemaps/ios-places-swift-sdk.
• حدِّث رقم الإصدار إلى 0.1.0.
• في حال التثبيت يدويًا، نزِّل البرامج الثنائية لحزمة تطوير البرامج (SDK) وملفات الموارد التالية:
  • GooglePlacesSwift
  • GooglePlacesSwiftResources
  • GooglePlaces
  • GooglePlacesResources

على سبيل المثال، في حال استخدام 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

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()
    }
  }