إعداد مشروع Xcode

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

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

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

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

  1. الإصدار Xcode من الإصدار 14.0 أو إصدار أحدث
  2. Cocoapods أو قرطاج

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

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

استخدام Cocoapods

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

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

sudo gem install cocoapods

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

  1. إذا لم يكن لديك مشروع Xcode بعد، يمكنك إنشاؤه الآن وحفظه في جهازك المحلي. إذا كنت لا تزال مبتدئًا في مجال تطوير تطبيقات iOS، أنشِئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
  2. أنشِئ ملفًا باسم Podfile في دليل مشروعك. يحدِّد هذا الملف اعتماديات مشروعك.
  3. يمكنك تعديل Podfile وإضافة الاعتماديات مع إصداراتها. في ما يلي مثال يحدّد اسم التطبيق المستهدَف واسم مجموعة الإعلانات GooglePlaces: 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '14.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GooglePlaces', '8.0.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) للأماكن التي تعمل بنظام التشغيل iOS متاحة للاستخدام مع تطبيق Carthage، وهو مدير اعتمادية لامركزي بسيط لمشاريع Swift وGOAL-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. في Finder (الباحث)، انتقِل إلى إطار عمل المشروع الذي تم تنزيله ضمن Carthage/Build/iOS في دليل مشروعك.
  9. اسحب الحِزم التالية إلى مشروعك (عندما يُطلب منك اختيار نسخ العناصر إذا لزم الأمر):
    • GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
  10. انقر بزر الماوس الأيمن على GooglePlaces.xcframework في مشروعك، واختَر إظهار في الباحث.
  11. اسحب السمة GooglePlaces.bundle من المجلد Resources إلى مشروعك. تأكّد من عدم اختيار نسخ العناصر إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.
  12. اختَر مشروعك من خلال Project Navigator، ثم اختَر هدف التطبيق.
  13. افتح علامة التبويب إصدارات المراحل، وضمن ربط برنامج ثنائي بالمكتبات، أضِف أُطر العمل والمكتبات التالية:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework

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

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

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

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

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

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

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

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

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

تثبيت إطار عمل CCframework

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

مع قرطاج

إنّ حزمة تطوير البرامج (SDK) للأماكن التي تعمل بنظام التشغيل iOS متاحة للاستخدام مع Carthage، وهو مدير اعتمادية لامركزي بسيط لمشاريع Swift وGOAL-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. اختَر مشروعك بدلاً من هدف محدَّد وافتح علامة تبويب إعدادات الإصدار.

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

يدويًا

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

  1. نزِّل ملفات مصدر حزمة تطوير البرامج (SDK): Googleالأماكن-8.0.0.
  2. فُكَّ حزمة ملفات المصدر. انتقِل إلى المجلد frameworks للوصول إلى XCframework.
  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. اختَر مشروعك بدلاً من هدف محدَّد وافتح علامة تبويب إعدادات الإصدار.

  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.