إعداد مشروع Xcode

Swift Package Manager

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

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

1. افتح Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة.
2. أدخِل https://github.com/googlemaps/ios-navigation-sdk كعنوان URL، واضغط على مفتاح الإدخال (Enter) لجلب الحزمة، وانقر على "إضافة حزمة" (Add Package).
3. لتثبيت version معيّن، اضبط الحقل قاعدة الاعتمادية (Dependency Rule) على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصحك بتحديد أحدث إصدار واستخدام الخيار "الإصدار الدقيق". بعد إتمام الخطوة السابقة، انقر على "إضافة حزمة".

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

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

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

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

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

اتّبِع الخطوات التالية لتثبيت XCFrameworks لحزمة تطوير البرامج للتنقّل على أجهزة iOS، وحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS:

1. نزِّل الملفات الثنائية وملفات الموارد التالية لحزمة تطوير البرامج:
   • GoogleMaps
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. شغِّل Xcode وافتح مشروعًا حاليًا أو أنشِئ مشروعًا جديدًا. إذا كنت جديدًا على iOS، أنشِئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
3. أزِل جميع مراجع "خرائط Google" و"التنقّل" و"الأماكن" الحالية من المشروع.
4. اسحب XCFrameworks التالية إلى مشروعك ضِمن الأطر والمكتبات والمحتوى المضمّن (Frameworks, Libraries, and Embedded Content) لتثبيت كلّ من حزمتَي تطوير البرامج "خرائط Google" و"التنقّل" (عندما يُطلب منك ذلك، اختَر نسخ العناصر إذا لزم الأمر (Copy items if needed)):
   • GoogleMaps.xcframework
   • GoogleNavigation.xcframework
5. اسحب GoogleMaps.bundle من GoogleMapsResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. عندما يُطلب منك ذلك، تأكَّد من اختيار نسخ العناصر إذا لزم الأمر (Copy items if needed).
6. اسحب GoogleNavigation.bundle من GoogleNavigationResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. عندما يُطلب منك ذلك، تأكَّد من اختيار نسخ العناصر إلى مجلد مجموعة الوجهة (Copy items into destination group's folder).
7. اختَر مشروعك من "مستكشف المشروع" (Project Navigator)، ثم اختَر هدف تطبيقك.
8. افتح علامة التبويب مراحل الإنشاء (Build Phases) ، وضِمن ربط الملفات الثنائية بالمكتبات (Link Binary with Libraries)، أضِف أُطر العمل والمكتبات التالية:
   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • CarPlay.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libxml2.tbd
   • libz.tbd
   • MapKit.framework
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework
   • UserNotifications.framework
   • WebKit.framework
9. في هدف تطبيقك، اختَر علامة التبويب الإمكانات (Capabilities)، فعِّل أوضاع التشغيل في الخلفية (Background Modes)، وفعِّل الأوضاع التالية:
   • الصوت وAirPlay ونافذة ضمن النافذة (Audio, AirPlay, and Picture in Picture)
   • تعديلات الموقع الجغرافي (Location updates)
10. اختَر مشروعك بدلاً من هدف معيّن، وافتح علامة التبويب Build Settings. في قسم علامات أداة الربط الأخرى (Other Linker Flags)، أضِف ‑ObjC لكلّ من تصحيح الأخطاء (debug) والإصدار (release). إذا لم تظهر هذه الإعدادات، غيِّر الفلتر في شريط إعدادات الإصدار (Build Settings) من أساسي (Basic) إلى الكل (All).
11. افتح Info.plist وأضِف أزواج المفتاح/القيمة التالية:
    • المفتاح: NSLocationWhenInUseUsageDescription (الخصوصية - وصف استخدام الموقع الجغرافي أثناء الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي لاتجاهات مفصّلة."
    • المفتاح: NSLocationAlwaysAndWhenInUseUsageDescription (الخصوصية - وصف استخدام الموقع الجغرافي دائمًا وأثناء الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي للاتجاهات المفصّلة."

CocoaPods

تتوفّر حزمة تطوير البرامج للتنقّل على أجهزة iOS كحزمة CocoaPods. ‫CocoaPods هو نظام مفتوح المصدر لإدارة التبعيات في مشاريع Cocoa التي تستخدم لغتَي Swift وObjective-C

إذا لم تكن لديك أداة CocoaPods، ثبِّتها على macOS من خلال تنفيذ الأمر التالي من المحطة الطرفية. لمعرفة التفاصيل، يُرجى الاطّلاع على دليل البدء في CocoaPods.

sudo gem install cocoapods

أنشِئ Podfile لحزمة تطوير البرامج للتنقّل على أجهزة iOS واستخدِم ه لتثبيت واجهة برمجة التطبيقات والملفات التابعة لها:

1. إذا لم يكن لديك مشروع Xcode بعد، أنشِئ مشروعًا الآن واحفظه على جهازك المحلي. إذا كنت جديدًا على تطوير تطبيقات iOS:
   1. أنشِئ مشروعًا جديدًا.
   2. اختَر نموذج iOS > التطبيق (App).
   3. على شاشة خيارات المشروع:
      1. أدخِل اسم المشروع (Project Name).
      2. سجِّل قيمة حقل معرّف الحزمة (Bundle identifier). يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على Storyboard.
      4. اضبط اللغة (Language) على Swift أو Objective-C.
2. أنشِئ ملفًا باسم Podfile في دليل مشروعك. يحدّد هذا الملف التبعيات في مشروعك.
3. عدِّل Podfile وأضِف التبعيات مع إصداراتها. إليك مثال يتضمّن الاعتمادية التي تحتاج إليها لحزمة تطوير البرامج للتنقّل على أجهزة iOS: # Cocoapods install reference #

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleNavigation', '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 إلى أحدث إصدار.

Swift

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

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

   import GoogleMaps
   import GoogleNavigation

2. أضِف ما يلي إلى طريقة application(_:didFinishLaunchingWithOptions:):

   GMSServices.provideAPIKey("YOUR_API_KEY")

Objective-C

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

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

   @import GoogleMaps;
   @import GoogleNavigation;

2. أضِف ما يلي إلى طريقة application:didFinishLaunchingWithOptions::

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];