إعداد مشروع Xcode

بعد تفعيل الفوترة وإنشاء مفتاح واجهة برمجة التطبيقات، ستكون جاهزًا لإعداد مشروع Xcode الذي تستخدمه لتطوير تطبيقك.

تتوفر ملاحظات الإصدار لكل .

الخطوة 1: تثبيت البرنامج المطلوب

لإنشاء مشروع باستخدام حزمة تطوير برامج الأماكن لنظام التشغيل iOS، ستحتاج إلى ما يلي:

  • Xcode الإصدار 15.0 أو إصدار أحدث

الخطوة 2: إنشاء مشروع Xcode وتثبيت حِزمة تطوير البرامج (SDK) للأماكن لنظام التشغيل iOS

مدير حزم Swift

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

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

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

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

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

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

    • GoogleMapsBase (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
    • GoogleMapsCore (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
    • GoogleMapsM4B (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
  2. من Xcode، انتقل إلى "File >" (ملف >) الحزم > التحديث إلى أحدث إصدارات الحزمة".
  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.

لإزالة حزمة SDK الحالية للأماكن في نظام التشغيل iOS والتي تم تثبيتها يدويًا، اتبع هذه الخطوات:
  1. من إعدادات ضبط مشروع Xcode، ابحث عن Frameworks وLibraries والمحتوى المضمَّن استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:
    • GooglePlaces.xcframework
  2. من دليل المستوى الأعلى لمشروع Xcode، عليك إزالة GooglePlaces. حُزم.

CocoaPods

تتوفر حزمة تطوير برامج الأماكن لنظام التشغيل iOS من خلال إصدار CocoaPod. pod، GooglePlaces، والتي تحتوي على جميع إمكانيات الأماكن.

CocoaPods هو مدير تبعية مفتوح المصدر لكلٍّ من Swift وObjective-C مشروعات الكاكاو. إذا لم تكن أداة 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 وملفات الموارد التالية لحزمة تطوير البرامج (SDK):
  2. يمكنك استخراج الملفات للوصول إلى XCFramework والموارد.
  3. ابدأ تشغيل Xcode وافتح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا مشروعك. إذا كنت مبتدئًا في مجال تطوير نظام التشغيل iOS، أنشئ مشروعًا جديدًا اختَر نموذج تطبيق iOS.
  4. يجب إزالة أي حِزم في "خرائط Google" من الإصدارات السابقة من مشروعك.
  5. افتح علامة التبويب "إعدادات عامة". اسحب XCFramework التالي إلى مشروعك. ضِمن أُطر العمل والمكتبات والمحتوى المضمَّن. يُرجى التأكد من أنّ: لتحديد عدم التضمين:
    • GooglePlaces.xcframework
  6. اسحب GooglePlaces.bundle من GooglePlacesResources الذي نزّلته
  7. انسخ GooglePlaces.bundle من GooglePlacesResources قمت بتنزيلها في دليل المستوى الأعلى لمشروع Xcode. تأكد من تحديد انسخ العناصر إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.
  8. اختَر مشروعك من Project Navigator، ثم اختَر هدف التطبيق.
  9. افتح علامة التبويب مراحل التصميم. ضمن Link Binary with المكتبات، أضِف أُطر العمل والمكتبات التالية:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  10. اختر مشروعك بدلاً من هدف محدد، وافتح علامة التبويب إعدادات الإصدار في الربط - عام -> رابط آخر قسم العلامات، أضِف -ObjC إلى "تصحيح الأخطاء" و"إصدار". إذا كانت هذه تكون الإعدادات غير مرئية، فغيّر الفلتر في شريط إعدادات التصميم من أساسي إلى الكل.

GooglePlacesSwift

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

على سبيل المثال، في حال استخدام 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: إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

في الأمثلة التالية، استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

Swift

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.swift على النحو التالي:

  • أضف عبارة الاستيراد التالية:
    import GooglePlaces
  • أضِف ما يلي إلى application(_:didFinishLaunchingWithOptions:) ، مع استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات:
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.m على النحو التالي:

  • أضف عبارة الاستيراد التالية:
    @import GooglePlaces;
  • أضِف ما يلي إلى application:didFinishLaunchingWithOptions: ، مع استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات:
    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

GooglePlacesSwift

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.swift على النحو التالي:

  • أضف عبارة الاستيراد التالية:
    import GooglePlacesSwift
  • أضِف ما يلي إلى application(_:didFinishLaunchingWithOptions:) ، مع استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات:
    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()
    }
  }
  

الخطوات التالية

بعد تهيئة مشروعك، يمكنك استكشاف نماذج التطبيقات.