إعداد مشروع Xcode

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

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

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

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

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

الخطوة 2: إنشاء مشروع Xcode وتثبيت حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS

ملاحظة: تضيف حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS متوسط حجم ملف IPA يبلغ 5.7 ميغابايت للتطبيقات المصمّمة لأجهزة معيّنة. قد يكون حجم تنزيل التطبيقات العامة أكبر.

يختلف حجم تثبيت حزمة SDK. على سبيل المثال، يبلغ حجم التثبيت للإصدار 9.0 من حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS حوالي 18 ميغابايت.

ملاحظة: في الإصدار 9.2.0، تم دمج GoogleMapsCore وGoogleMapsBase في GoogleMaps XCFramework. لا يلزم إجراء أيّ عملية إعداد إضافية.

لا تتوافق حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS حاليًا مع المكتبات القابلة للدمج. لتجنُّب حدوث أعطال في أداة الربط أثناء إنشاء إصدارات التطبيق، تأكَّد من ضبط الإعداد إنشاء مكتبة قابلة للدمج في مشروع Xcode على لا (الإعداد التلقائي).

Swift Package Manager

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

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

1. افتح Xcode project‏ أو workspace، ثم انتقِل إلى ملف > إضافة موارد الاعتمادية للحزمة (File > Add Package Dependencies).
2. أدخِل https://github.com/googlemaps/ios-maps-sdk كعنوان URL، واضغط على Enter لجلب الحزمة، ثم انقر على "إضافة حزمة".
3. لتثبيت version معيّن، اضبط الحقل قاعدة الاعتمادية على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصحك بتحديد أحدث إصدار واستخدام الخيار "الإصدار الدقيق". بعد إتمام الخطوة السابقة، انقر على "إضافة حزمة".
4. من نافذة اختيار منتجات الحزمة ، تأكَّد من أنّه سيتم إضافة GoogleMaps (بالنسبة إلى الإصدارات الأقدم من 9.0.0، تأكَّد من إضافة GoogleMaps وGoogleMapsBase و GoogleMapsCore) إلى main الهدف المحدّد. بعد إتمام الخطوة السابقة، انقر على "إضافة حزمة".
5. للتأكّد من عملية التثبيت، انتقِل إلى لوحة عام الخاصة بالهدف. في الأطر والمكتبات والمحتوى المضمّن ، يجب أن تظهر الحِزم المثبَّتة. يمكنك أيضًا عرض قسم "موارد الاعتمادية للحزمة" في "مستكشف المشروع" للتأكّد من الحزمة وإصدارها.

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

1. إذا كنت بصدد الترقية من إصدار أقدم من 9.0.0، عليك إزالة موارد الاعتمادية التالية: GoogleMapsBase وGoogleMapsCore وGoogleMapsM4B بعد الترقية. لا تُزِل الاعتمادية الخاصة بـ GoogleMaps. لمزيد من المعلومات، يُرجى الاطّلاع على ملاحظات الإصدار 9.0.0.

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

   • GoogleMapsBase (لعمليات الترقية من إصدارات أقدم من 9.0.0 فقط)
   • GoogleMapsCore (لعمليات الترقية من إصدارات أقدم من 9.0.0 فقط)
   • GoogleMapsM4B (لعمليات الترقية من إصدارات أقدم من 9.0.0 فقط)
2. من Xcode، انتقِل إلى ملف > الحِزم > تعديل إلى أحدث إصدارات الحزمة (File > Packages > Update To Latest Package Versions).
3. للتأكّد من عملية التثبيت، انتقِل إلى قسم موارد الاعتمادية للحزمة في مستكشف المشروع للتأكّد من الحزمة وإصدارها.

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

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

1. أغلِق مساحة عمل Xcode. افتح الوحدة الطرفية ونفِّذ الأمر التالي:

   sudo gem install cocoapods-deintegrate cocoapods-clean
   pod deintegrate
   pod cache clean --all

2. أزِل Podfile وPodfile.resolved و Xcode workspace إذا كنت لا تستخدمها لأي غرض آخر غير CocoaPods.

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

1. من إعدادات ضبط مشروع Xcode، ابحث عن الأطر والمكتبات، والمحتوى المضمّن. استخدِم علامة الطرح (-) لإزالة إطار العمل التالي:
   • GoogleMaps
   • GoogleMapsBase (لعمليات التثبيت الأقدم من الإصدار 9.2.0 فقط)
   • GoogleMapsCore (لعمليات التثبيت الأقدم من الإصدار 9.2.0 فقط)
   • GoogleMapsM4B (لعمليات التثبيت الأقدم من الإصدار 9.0.0 فقط)
2. من دليل المستوى الأعلى لمشروع Xcode، أزِل حزمة GoogleMaps.

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

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

1. نزِّل ملفات SDK الثنائية وملفات الموارد التالية:
   • GoogleMaps
   • GoogleMapsResources
2. استخرِج الملفات للوصول إلى XCFrameworks والموارد.
3. إذا لم يكن لديك مشروع Xcode بعد، أنشِئ مشروعًا الآن واحفظه على جهازك المحلي. إذا كنت جديدًا على تطوير تطبيقات iOS:
   1. أنشِئ مشروعًا جديدًا.
   2. اختَر نموذج iOS > تطبيق.
   3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على Storyboard.
      4. اضبط اللغة على Swift أو Objective-C.
4. افتح علامة التبويب عام. اسحب XCFrameworks التالية إلى مشروعك ضمن الأطر والمكتبات والمحتوى المضمّن. احرص على اختيار عدم التضمين:
   • GoogleMaps.xcframework
5. انسخ GoogleMaps.bundle من GoogleMapsResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد مجموعة الوجهة عند ظهور الرسالة.
6. اختَر مشروعك من "مستكشف المشروع"، ثم اختَر هدف تطبيقك.
7. افتح علامة التبويب مراحل الإنشاء (Build Phases) الخاصة بهدف تطبيقك. في ربط الملفات الثنائية بالمكتبات (Link Binary with Libraries)، أضِف أُطر العمل والمكتبات التالية:
   • Accelerate.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • MetricKit.framework
   • OpenGLES.framework (إذا كنت تستخدم OpenGL فقط)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. اختَر مشروعك بدلاً من هدف معيّن، وافتح علامة التبويب إعدادات الإنشاء (Build Settings). في قسم الربط - عام - > علامات أداة الربط الأخرى (Linking - General -> Other Linker Flags) ، أضِف -ObjC إلى "تصحيح الأخطاء" و"الإصدار". إذا لم تظهر هذه الإعدادات، غيِّر الفلتر في شريط إعدادات الإنشاء (Build Settings) من أساسي (Basic) إلى الكل (All).

9. لتثبيت XCFramework لحزمة تطوير برامج الأماكن لأجهزة iOS، اطّلِع على مقالة البدء باستخدام حزمة تطوير برامج الأماكن لأجهزة iOS.

الخطوة 3: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

في مقالة الحصول على مفتاح واجهة برمجة تطبيقات، أنشأت مفتاح واجهة برمجة تطبيقات لتطبيقك. والآن، أضِف هذا المفتاح إلى مشروع Xcode.

في الأمثلة التالية، استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

ملاحظة: إذا سجّلت معرّف الحزمة لمشروعك أو حصلت عليه من خصائص المشروع، استخدِمه لتقييد مفتاح واجهة برمجة التطبيقات بحيث لا يتم استخدامه إلا مع تطبيقات iOS التي تحمل معرّف الحزمة المحدّد هذا. لمزيد من المعلومات، اطّلِع على مقالة تقييد مفاتيح واجهة برمجة التطبيقات.

Swift

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

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

   import GoogleMaps

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

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. إذا كنت تستخدم أيضًا Places API، أضِف مفتاحك مرة أخرى كما هو موضّح هنا:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

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

   @import GoogleMaps;

2. أضِف ما يلي إلى طريقة application:didFinishLaunchingWithOptions: باستخدام مفتاح واجهة برمجة التطبيقات:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. إذا كنت تستخدم أيضًا Places API، أضِف مفتاحك مرة أخرى كما هو موضّح هنا:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

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

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

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

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

الخطوة 5 (اختيارية): الإعلان عن مخططات عناوين URL التي تستخدمها واجهة برمجة التطبيقات

بدءًا من نظام التشغيل iOS 9 وXcode 7، تعلن التطبيقات عن مخططات عناوين URL التي تنوي فتحها من خلال تحديد المخططات في ملف Info.plist الخاص بالتطبيق. تفتح حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS تطبيق "خرائط Google" للأجهزة الجوّالة عندما ينقر المستخدم على شعار Google على الخريطة، وبالتالي يمكن لتطبيقك الإعلان عن مخططات عناوين URL ذات الصلة.

للإعلان عن مخططات عناوين URL التي تستخدمها حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع iOS، أضِف الأسطر التالية إلى Info.plist:

 <key>LSApplicationQueriesSchemes</key>
 <array>
        <string>googlechromes</string>
        <string>comgooglemaps</string>
    </array>

تعرِض الصورة التالية الإعدادات في واجهة مستخدم Xcode:

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

• -canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
• -canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

لإزالة هذه الأخطاء، أضِف الإعلان إلى Info.plist.

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

بعد الحصول على مفتاح واجهة برمجة تطبيقات ومشروع Xcode، يمكنك إنشاء التطبيقات وتشغيلها. توفّر حزمة تطوير البرامج للتنقّل على أجهزة iOS العديد من الأدلة التعليمية والتطبيقات النموذجية التي تساعدك في البدء. لمزيد من التفاصيل، اطّلِع على ما يلي:

• إضافة خريطة بعلامة.
• اختيار المكان الحالي وعرض التفاصيل على خريطة.
• عكس الترميز الجغرافي.
• اطّلِع على نماذج الرموز البرمجية وورش العمل البرمجية المتاحة.
• للاطّلاع على الحلول الشاملة، راجِع حلول "خرائط Google" المتاحة.