إعداد مشروع Xcode

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

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

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

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

  • الإصدار 14.0 من Xcode أو إصدار أحدث

الخطوة 2: إنشاء مشروع Xcode وتثبيت حزمة تطوير برامج الأماكن لأجهزة iOS

مدير حِزم Swift

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

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

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

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

  1. من Xcode، انتقل إلى "ملف > الحزم > التحديث إلى أحدث إصدارات الحزمة".
  2. للتحقّق من التثبيت، انتقِل إلى قسم تبعيات الحزمة في 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.

لإزالة حزمة تطوير برامج الأماكن الحالية لنظام التشغيل iOS التي تم تثبيتها يدويًا، اتّبع الخطوات التالية:

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

كاكابود

تتوفّر حزمة تطوير برامج الأماكن لأجهزة 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 وأضِف التبعيات الخاصة بك مع versions. في ما يلي مثال يحدّد اسم استهداف التطبيق واسم مجموعة 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 الذي يحتوي على حزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل iOS يدويًا إلى مشروعك وضبط إعدادات تصميمك في Xcode. XCFramework هي حزمة ثنائية يمكنك استخدامها على أنظمة أساسية متعددة، بما في ذلك الأجهزة التي تستخدم Apple silicon.

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

الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

في الأمثلة التالية، استبدِل 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"];

الخطوة 4: بدء كتابة الرمز

توضّح نماذج الرموز التالية كيفية الوصول إلى المكان الحالي.

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
      

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

بعد ضبط مشروعك، يمكنك استكشاف نماذج التطبيقات. يجب تثبيت الإصدار 1.6.1 من Cocoapods.