إعداد مشروع Xcode

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

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

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

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

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

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

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

استخدام Cocoapods

تتوفر حزمة تطوير برامج الأماكن (SDK) لنظام التشغيل iOS في شكل لوحة CocoaPod المتسلسلة، وهي GooglePlaces التي تحتوي على جميع وظائف الأماكن.

CocoaPods هي مديرة اعتمادية مفتوحة المصدر لمشاريع Cocoa وSwift. إذا لم تكن لديك أداة 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, '14.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. اسحب XCFramework التالي إلى مشروعك ضمن Frameworks والمكتبات والمحتوى المضمَّن. تأكّد من اختيار عدم التضمين:
   • GooglePlaces.xcframework
6. اسحب GooglePlaces.bundle من GooglePlacesResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode الخاص بك. تأكَّد من اختيار نسخ العناصر إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.
7. اختَر مشروعك من Project Navigator، واختَر هدف تطبيقك.
8. افتح علامة التبويب مراحل الإنشاء، وضمن ربط النظام الثنائي مع المكتبات، أضِف أُطر العمل والمكتبات التالية:
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

9. اختَر مشروعك بدلاً من هدف محدّد، ثم افتح علامة التبويب إعدادات الإصدار.

10. في القسم علامات الروابط الأخرى، أضِف -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.