إعداد مشروع Xcode

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

اتّبِع الخطوات الواردة في هذا الدليل لتنزيل حزمة تطوير البرامج (SDK) لأماكن Google لنظام التشغيل iOS لإضافة المكتبة وملحقاتها إلى تطبيقك والحصول على مفتاح واجهة برمجة التطبيقات بدون أي رسوم.

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

الخطوة 1: الحصول على أحدث إصدار من Xcode

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

  1. Xcode الإصدار 13.0 أو الإصدارات الأحدث.
  2. Cocoapods أو Carthage

الخطوة 2: تثبيت حزمة تطوير البرامج (SDK)

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

استخدام Cocoapods

تتوفّر حزمة تطوير البرامج (SDK) الخاصة بخدمة Places لـ iOS على شكل لوحة CocoaPod، وهي Google Places التي تتضمّن جميع وظائف الأماكن.

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

sudo gem install cocoapods

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

  1. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على الجهاز المحلي. إذا كنت أحدث إصدار من تطوير نظام التشغيل iOS، أنشئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
  2. أنشِئ ملفًا باسم Podfile في دليل المشروع. يحدّد هذا الملف تبعيات مشروعك.
  3. عدِّل Podfile وأضِف المهام التابعة لك مع إصداراتها. إليك مثال يحدّد اسم هدف التطبيق واسم لوحة GooglePlaces:
    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '13.0'
    
    target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
      pod 'GooglePlaces', '7.1.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 إلى أحدث إصدار.

استخدام قرطاج

إن حزمة تطوير البرامج (SDK) لأماكن Google لنظام التشغيل iOS متاحة للاستخدام مع Carthage، وهو مدير بسيط اعتمادي للاعتمادية من أجل مشاريع Swift وPurpose-C Cocoa.

  1. تثبيت قرطاج. ثمة طرق متعدّدة، لذلك الاطّلاع على ملف README لقرطاج لمعرفة الخطوات الدقيقة.
  2. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على الجهاز المحلي. إذا كنت أحدث إصدار من تطوير نظام التشغيل iOS، أنشئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
  3. أنشِئ ملفًا باسم Cartfile في دليل المشروع. يحدّد هذا الملف تبعيات مشروعك.
  4. عدِّل Cartfile وأضِف الاعتماديات مع إصداراتها:
     binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1
    تأكّد من تشغيل carthage outdated بانتظام لاكتشاف أي إصدارات أحدث لضمان حصولك على آخر المعلومات دائمًا.
  5. احفظ Cartfile.
  6. في نافذة المحطة الطرفية، انتقِل إلى الدليل الذي يتضمّن Cartfile:
    cd <path-to-project>
  7. شغِّل الأمر carthage update. سيؤدي هذا الإجراء إلى تثبيت واجهات برمجة التطبيقات المحدّدة في السمة Cartfile، إلى جانب أي تبعيات قد تكون لديهم.
  8. في "الباحث"، في دليل المشروع، انتقِل إلى ملفات إطار العمل التي تم تنزيلها ضمن Carthage/Build/iOS.
  9. اسحب الحِزم التالية إلى مشروعك (عندما يُطلب منك ذلك، اختَر نسخ العناصر إذا لزم الأمر):
    • GooglePlaces-5.x.x/Frameworks/GooglePlaces.framework
  10. انقر بزر الماوس الأيمن على GooglePlaces.framework في المشروع، واختَر إظهار في الباحث.
  11. اسحب GooglePlaces.bundle من مجلد Resources إلى مشروعك. تأكّد من عدم اختيار نسخ العناصر إلى مجلد المجموعة المقصودة عندما يُطلب منك ذلك.
  12. اختَر مشروعك من Project Navigator (أداة التنقّل) واختَر هدف التطبيق.
  13. افتح علامة التبويب Build مراحل، وضمن ربط برنامج ثنائي بالمكتبات، أضِف أُطر العمل والمكتبات التالية:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  14. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب Settings Settings (إعدادات الإصدار).

  15. في قسم علامات الروابط الأخرى، أضِف -ObjC. في حال عدم ظهور هذه الإعدادات، يمكنك تغيير الفلتر في شريط إعدادات الإصدار من أساسي إلى الكل.

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

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

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

يشرح هذا الدليل كيفية إضافة إطار عمل "أماكن Google" إلى مشروعك يدويًا، ثم ضبط إعدادات الإصدار في Xcode.

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

  11. في قسم علامات الروابط الأخرى، أضِف -ObjC. في حال عدم ظهور هذه الإعدادات، يمكنك تغيير الفلتر في شريط إعدادات الإصدار من أساسي إلى الكل.

تثبيت XCframework

XCframework هي حزمة ثنائية يمكنك استخدامها على أنظمة أساسية متعددة، بما في ذلك الأجهزة التي تستخدم شريحة M1، لتثبيت حزمة تطوير برامج الأماكن (SDK) لنظام التشغيل iOS. يوضح هذا الدليل كيفية إضافة XCframework الذي يحتوي على حزمة تطوير البرامج (SDK) لأماكن Google لنظام التشغيل iOS إلى مشروعك وإعداد إعدادات الإصدار في Xcode.

مع قرطاج

تتوفّر حزمة تطوير البرامج (SDK) لأماكن Google لنظام التشغيل iOS للاستخدام مع Carthage، وهو مدير بسيط تابع للمركزية عن مشاريع Swift وPurpose-C Cocoa.

  1. تثبيت قرطاج. ثمة طرق متعدّدة، لذلك الاطّلاع على ملف README لقرطاج لمعرفة الخطوات الدقيقة.
  2. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على الجهاز المحلي. إذا كنت أحدث إصدار من تطوير نظام التشغيل iOS، أنشئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
  3. أنشِئ ملفًا باسم Cartfile في دليل المشروع. يحدّد هذا الملف تبعيات مشروعك.
  4. عدِّل Cartfile وأضِف تبعياتك مع إصداراتها:

    binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1-beta
  5. احفظ Cartfile.
  6. في نافذة طرفية، انتقِل إلى الدليل الذي يحتوي على Cartfile:

    cd <path-to-project>
  7. شغِّل الأمر carthage update. سيؤدي هذا الإجراء إلى تثبيت واجهات برمجة التطبيقات المحدّدة في السمة Cartfile، إلى جانب أي تبعيات قد تكون لديهم.
  8. في"الباحث"، في دليل المشروع، انتقِل إلى ملفات إطار العمل التي تم تنزيلها ضمن Carthage/Build.
  9. اسحب XCframework التالي إلى مشروعك ضمن الإطارات والمكتبات والمحتوى المُضمَّن. احرص على تحديد عدم التضمين:
    • GooglePlaces-x.x.x/GooglePlaces.xcframework
  10. انقر بزر الماوس الأيمن على GooglePlaces.xcframework في المشروع، واختَر عرض في الباحث.
  11. اسحب GooglePlaces.bundle من مجلد ios-arm64/GooglePlaces.framework/Resources إلى دليل المستوى الأعلى في مشروع Xcode. تأكّد من عدم اختيار نسخ العناصر إلى مجلد مجموعة الوجهة عندما يُطلب منك ذلك.
  12. اختَر مشروعك من Project Navigator (أداة التنقّل) واختَر هدف التطبيق.
  13. افتح علامة التبويب إصدار المراحل، وفي ربط برنامج ثنائي بالمكتبات، وأضِف أُطر العمل والمكتبات التالية:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework
  14. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب Settings Settings (إعدادات الإصدار).

  15. في قسم علامات الروابط الأخرى، أضِف -ObjC. في حال عدم ظهور هذه الإعدادات، يمكنك تغيير الفلتر في شريط إعدادات الإصدار من أساسي إلى الكل.

يدويًا

يوضح هذا الدليل كيفية إضافة حزمة تطوير البرامج (SDK) للخرائط إلى نظام التشغيل iOS يدويًا إلى مشروعك وإعداد إعدادات الإصدار في Xcode.

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

  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.