إعداد مشروع Xcode

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

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

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

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

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

الخطوة الثانية: تثبيت SDK

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

استخدام Cocoapods

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

CocoaPods هو مدير تبعية مصدر مفتوح المصدر لمشروعات Swift وGoal-C Cocoa. إذا لم يكن لديك أداة 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, '13.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GooglePlaces', '7.4.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 إلى أحدث إصدار.

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

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

تتوفر حزمة 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. في "الباحث"، في دليل المشروع، انتقِل إلى ملفات أُطر العمل التي تم تنزيلها ضمن 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): GooglePlaces-7.4.0
2. فك ضغط ملفات المصدر.
3. شغّل Xcode وافتَح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا. إذا كنت مستخدمًا جديدًا في مجال تطوير نظام التشغيل iOS، فأنشئ مشروعًا جديدًا وحدد نموذج تطبيق iOS.
4. أزِل أي حِزم خرائط من الإصدارات السابقة من مشروعك.
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. إذا لم تكن هذه الإعدادات مرئية، فغيّر الفلتر في شريط إعدادات الإصدار من أساسي إلى الكل.

تثبيت XCFramework

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

1. نزِّل ملفات المصدر لحزمة تطوير البرامج (SDK): GooglePlaces-7.4.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"];

الخطوة الرابعة: بدء كتابة الشفرة

توضح نماذج الشفرة التالية كيفية الحصول على المكان الحالي.

يُرجى ملاحظة، لأن هذا النموذج يتطلب الوصول إلى موقع الجهاز للحصول على الموقع الحالي، ستحتاج إلى تعيين مفتاح NSLocationWhenInUseUsageDescription باستخدام نص توضيحي مناسب في ملف Info.plist لمشروعك. للحصول على مزيد من التفاصيل، يمكنك الاطّلاع على دليل الحصول على المكان الحالي.

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
      

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

بعد تهيئة مشروعك، يمكنك استكشاف نماذج التطبيقات. ستحتاج إلى تثبيت Cocoapods v1.6.1.