إعداد مشروع Xcode

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

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

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

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

• Xcode الإصدار 26.0 أو الإصدارات الأحدث

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

Swift Package Manager

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

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

1. افتح Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة.
2. أدخِل https://github.com/googlemaps/ios-places-sdk كعنوان URL، واضغط على مفتاح الإدخال لجلب الحزمة، ثم انقر على "إضافة حزمة".
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. للتأكّد من عملية التثبيت، انتقِل إلى لوحة عام الخاصة بالهدف. في الأطر والمكتبات والمحتوى المضمّن، من المفترض أن تظهر الحِزم المثبَّتة. يمكنك أيضًا الاطّلاع على قسم موارد الاعتمادية للحزمة في مستكشف المشروع للتأكّد من الحزمة وإصدارها.

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

1. من Xcode، انتقِل إلى "ملف > الحِزم > تعديل إلى أحدث إصدارات الحزمة (File > Packages > Update To Latest Package Versions)".

   إذا كنت بصدد تعديل 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. للتأكّد من عملية التثبيت، انتقِل إلى قسم موارد الاعتمادية للحزمة في مستكشف المشروع للتأكّد من الحزمة وإصدارها.

ملاحظة مهمة: في بعض الأحيان، لا يمكن حلّ البيانات الاصطناعية أو قد تحدث أخطاء. في هذه الحالة، اختَر "ملف > الحِزم > إعادة ضبط ذاكرة التخزين المؤقت للحزمة (File > Packages > Reset Package Cache)".

لإزالة حزمة تطوير برامج الأماكن لأجهزة iOS المثبَّتة يدويًا، اتّبِع الخطوات التالية:

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

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

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

1. نزِّل ملفات SDK الثنائية وملفات الموارد التالية:
   • GooglePlaces
   • GooglePlacesResources
2. إذا كنت بصدد تثبيت حزمة تطوير برامج الأماكن لأجهزة iOS بلغة Swift، ثبِّت الملفات التالية:
   • GooglePlacesSwift
   • GooglePlacesSwiftResources
3. استخرِج الملفات للوصول إلى XCFramework والموارد.
4. شغِّل Xcode وافتح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا. إذا كنت جديدًا على تطوير تطبيقات iOS، أنشئ مشروعًا جديدًا و اختر نموذج تطبيق iOS.
5. أزِل أي حِزم خرائط من الإصدارات السابقة من مشروعك.
6. افتح علامة التبويب عام. اسحب XCFramework التالية إلى مشروعك ضمن الأطر والمكتبات والمحتوى المضمّن. احرص على اختيار عدم التضمين:
   • GooglePlaces.xcframework
   إذا كنت بصدد تثبيت حزمة تطوير برامج الأماكن لأجهزة iOS بلغة Swift، اسحب XCFramework التالية إلى مشروعك ضمن الأطر والمكتبات والمحتوى المضمّن. احرص على اختيار عدم التضمين:
   • GooglePlacesSwift.xcframework
7. انسخ GooglePlaces.bundle من GooglePlacesResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد مجموعة الوجهة عند ظهور الرسالة.
   
   إذا كنت بصدد تثبيت حزمة تطوير برامج الأماكن لأجهزة iOS بلغة Swift، انسخ GooglePlacesSwift.bundle من GooglePlacesSwiftResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد مجموعة الوجهة عند ظهور الرسالة.
8. اختَر مشروعك من "مستكشف المشروع"، ثم اختَر هدف تطبيقك.
9. افتح علامة التبويب مراحل الإنشاء. في ربط الملفات الثنائية بالمكتبات (Link Binary with Libraries)، أضِف أُطر العمل والمكتبات التالية:
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

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

CocoaPods

ميزة متوقّفة: اعتبارًا من 18 أغسطس 2025، سيخضع CocoaPods للصيانة، ولن نطرح المزيد من الإصدارات بعد الربع الثاني من عام 2026. استخدِم Swift Package Manager بدلاً من ذلك.

تتوفّر حزمة تطوير برامج الأماكن لأجهزة iOS وحزمة تطوير برامج الأماكن لأجهزة iOS بلغة Swift كحِزم CocoaPod pods، وهما GooglePlaces وGooglePlacesSwift.

‫CocoaPods هو نظام مفتوح المصدر لإدارة التبعيات في مشاريع Cocoa التي تستخدم لغتَي Swift وObjective-C إذا لم يكن لديك أداة 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, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GooglePlaces', '10.13.0'
     pod 'GooglePlacesSwift', '10.13.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 بمفتاح واجهة برمجة التطبيقات.

GooglePlacesSwift

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

• أضِف عبارة الاستيراد التالية:

  import GooglePlacesSwift

• أضِف ما يلي إلى طريقة application(_:didFinishLaunchingWithOptions:) ، مع استبدال YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات:

  PlacesClient.provideAPIKey("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 (اختيارية): فحص ملف بيان الخصوصية من Apple

ملاحظة: ينطبق ما يلي عند نشر تطبيقك على متجر الويب.

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

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

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

• ابدأ كتابة الرمز. ننصحك بالبدء بتنفيذ تطبيق أساسي يحصل على المكان الحالي للمستخدم.
• بعد ضبط مشروعك، يمكنك استكشاف الـ تطبيقات النموذجية.
• استخدِم ميزة فحص التطبيقات لتأمين مفتاح واجهة برمجة التطبيقات.