إعداد مشروع Xcode

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

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

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

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

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

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

أداة إدارة حِزم Swift

يمكن تثبيت حزمة تطوير برامج "الأماكن" لنظام التشغيل iOS من خلال أداة Swift Package Manager. لإضافة حزمة تطوير البرامج، تأكَّد من أنّك أزلت أيّ تبعيات حالية لحزمة تطوير برامج "الأماكن" لنظام التشغيل iOS.

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

  1. افتح Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة تبعيات الحزمة.
  2. أدخِل https://github.com/googlemaps/ios-places-sdk كعنوان URL، واضغط على مفتاح Enter لسحب الحزمة، ثم انقر على "إضافة حزمة".
  3. لتثبيت version معيّن، اضبط حقل قاعدة التبعية على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصحك بتحديد أحدث إصدار و استخدام الخيار "الإصدار المحدّد". بعد الانتهاء، انقر على "إضافة حزمة".
  4. من نافذة اختيار منتجات الحزمة، تأكّد من أنّه سيتمّ إضافة GooglePlaces أو GooglePlacesSwift أو كليهما إلى الاستهداف الرئيسي المحدّد. بعد الانتهاء، انقر على إضافة حزمة.

    في حال كنت بصدد تحديث Google Places Swift من عنوان URL المتوقّف نهائيًا على GitHub

    ملاحظة مهمة: تغيّر عنوان URL على GitHub للوصول إلى Google Places Swift بدءًا من الإصدار 0.3.0. إذا كنت بصدد تحديث إصدار من GooglePlacesSwift تم الوصول إليه من خلال عنوان URL القديم، https://github.com/googlemaps/ios-places-swift-sdk، عليك إزالته من قسم "التبعيات في الحزمة" في Xcode.

  5. للتحقّق من عملية التثبيت، انتقِل إلى لوحة الإعدادات العامة لهدفك. في قسم الإطارات والكتب والمكتبات والمحتوى المضمّن، من المفترض أن تظهر لك الحِزم المثبَّتة. يمكنك أيضًا عرض قسم تبعيات الحزمة في Project Navigator (مستكشف المشاريع) للتحقّق من الحزمة وإصدارها. يعرض Xcode إصدار GitHub الذي يتطابق مع إصدار GooglePlaces (على سبيل المثال 9.2.0) ولكنّه لا يتطابق مع إصدار GooglePlacesSwift (على سبيل المثال 0.3.0).

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

  1. من Xcode، انتقِل إلى "ملف > حِزم > التحديث إلى أحدث إصدارات الحِزم".

    في حال كنت بصدد تحديث Google Places Swift من عنوان URL المتوقّف نهائيًا على GitHub

    ملاحظة مهمة: تغيّر عنوان URL على GitHub للوصول إلى Google Places Swift بدءًا من الإصدار 0.3.0. إذا كنت بصدد تحديث إصدار من GooglePlacesSwift تم الوصول إليه من خلال عنوان URL القديم، https://github.com/googlemaps/ios-places-swift-sdk، عليك إزالته من قسم "التبعيات في الحزمة" في Xcode.

  2. للتحقّق من عملية التثبيت، انتقِل إلى قسم تبعيات الحزمة في Project Navigator (مستكشف المشاريع) للتحقّق من الحزمة وإصدارها.

لإزالة حزمة Places SDK لنظام التشغيل iOS الحالية المثبَّتة يدويًا، يُرجى اتّباع الخطوات التالية:

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

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

يوضّح هذا الدليل كيفية إضافة حِزم XCFrameworks يدويًا التي تحتوي على حزمة تطوير برامج "الأماكن" لنظام التشغيل iOS وحزمة تطوير برامج Places Swift لنظام التشغيل iOS (إصدار تجريبي) إلى مشروعك وضبط إعدادات الإنشاء في Xcode. ‫XCFramework هي حزمة ثنائية يمكنك >استخدامها على أنظمة أساسية متعددة، بما في ذلك الأجهزة التي تستخدم شرائح Apple Silicon. يمكنك اختيار إضافة حزمة تطوير برامج "الأماكن" لنظام التشغيل iOS أو حزمة تطوير برامج Places Swift لنظام التشغيل iOS (إصدار تجريبي) أو كليهما.

  1. نزِّل الملفات الثنائية وملفات الموارد التالية لحزمة SDK:
  2. في حال تثبيت حزمة تطوير البرامج (SDK) لأماكن Swift لنظام التشغيل iOS (إصدار تجريبي)، ثبِّت الملفات التالية:
  3. استخرِج الملفات للوصول إلى XCFramework والموارد.
  4. افتح Xcode وافتَح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا. إذا كنت مبتدئًا في تطوير تطبيقات iOS، أنشئ مشروعًا جديدًا و اختَر نموذج تطبيق iOS.
  5. أزِل من مشروعك أي حِزم "خرائط Google" من الإصدارات السابقة.
  6. افتح علامة التبويب عام. اسحب إطار عمل XCFramework التالي إلى مشروعك ضمن الإطارات والمكتبات والمحتوى المضمّن. تأكَّد مما يلي لاختيار عدم التضمين:
    • GooglePlaces.xcframework
    في حال تثبيت حزمة Places Swift SDK لنظام التشغيل iOS (إصدار تجريبي)، اسحب إطار XCFramework التالي إلى مشروعك ضمن الإطارات والكتب والملفات المضمّنة. تأكَّد مما يلي لاختيار عدم التضمين:
    • GooglePlacesSwift.xcframework
  7. انسخ GooglePlaces.bundle من GooglePlacesResources الذي نزّلته إلى الدليل الأعلى لمشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.

    في حال تثبيت حزمة تطوير البرامج Places Swift SDK لنظام التشغيل iOS (إصدار تجريبي)، انسخ GooglePlacesSwift.bundle من GooglePlacesSwiftResources التي نزّلتها إلى الدليل الأعلى لمشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.
  8. اختَر مشروعك من "مستكشف المشاريع"، ثم اختَر استهداف تطبيقك.
  9. افتح علامة التبويب مراحل الإنشاء. ضمن ربط الثنائي بالمكتبات، أضِف الإطارات والمكتبات التالية:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework

  10. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات الإنشاء. في قسم الربط - عام -> علامات أدوات الربط الأخرى، أضِف -ObjC إلى "تصحيح الأخطاء" و "الإصدار". إذا لم تكن هذه الإعدادات مرئية، غيِّر الفلتر في شريط إعدادات الإنشاء من أساسي إلى الكل.

CocoaPods

تتوفّر حزمة تطوير البرامج (SDK) لتطبيق "الأماكن" لنظام التشغيل iOS وحزمة تطوير البرامج (SDK) لتطبيق "الأماكن" باستخدام Swift لنظام التشغيل iOS (إصدار تجريبي) كحِزم CocoaPod ، وGooglePlaces وGooglePlacesSwift.

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

sudo gem install cocoapods

أنشئ Podfile لتثبيت حِزم SDK والتبعيات المرتبطة بها:

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

platform :ios, '15.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GooglePlaces', '9.2.0'
  pod 'GooglePlacesSwift', '0.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 إلى أحدث إصدار.

الخطوة 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"];

GooglePlacesSwift

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.swift على النحو التالي:

  • أضِف بيان الاستيراد التالي: 
    import GooglePlacesSwift
  • أضِف ما يلي إلى طريقة application(_:didFinishLaunchingWithOptions:) ، مع استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك: 
    PlacesClient.provideAPIKey("YOUR_API_KEY")

الخطوة 4 (اختيارية): فحص ملف بيان الخصوصية من Apple

تشترط Apple تقديم تفاصيل خصوصية التطبيقات على App Store. يُرجى الانتقال إلى صفحة "تفاصيل الخصوصية" في Apple App Store للاطّلاع على آخر الأخبار والمزيد من المعلومات.

يتم تضمين ملف بيان الخصوصية من Apple في حِزمة الموارد لحزمة SDK. للتأكّد من تضمين ملف بيان الخصوصية وفحص محتوياته، أنشئ أرشيفًا لتطبيقك وأنشئ تقرير خصوصية من الأرشيف.

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