إعداد مشروع Xcode

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

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

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

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

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

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

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

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

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

Swift Package Manager

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

ملاحظة مهمة: تفترض هذه التعليمات استخدام الإصدار 15 من Xcode أو إصدار أحدث، ولكن من المفترض أن تكون الخطوات مشابهة في الإصدارات السابقة من Xcode.

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

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

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

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

   من إعدادات ضبط مشروع Xcode، ابحث عن Frameworks, Libraries, and Embedded Content. استخدِم علامة الطرح(-) لإزالة الإطار التالي:

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

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

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

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

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

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

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

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

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

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

1. نزِّل ملفات SDK الثنائية وملفات الموارد التالية:
   • GoogleMaps
   • GoogleMapsResources
2. استخرِج الملفات للوصول إلى XCFrameworks والموارد.
3. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على جهازك المحلّي. إذا كنت مبتدئًا في تطوير تطبيقات iOS:
   1. أنشِئ مشروعًا جديدًا.
   2. اختَر نموذج iOS > التطبيق.
   3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على مخطط القصة.
      4. اضبط اللغة على Swift أو Objective-C.
4. افتح علامة التبويب عام. اسحب ملف XCFramework التالي إلى مشروعك ضمن Frameworks, Libraries, and Embedded Content. احرص على اختيار عدم التضمين:
   • GoogleMaps.xcframework
5. انسخ GoogleMaps.bundle من GoogleMapsResources الذي نزّلته إلى الدليل الأعلى مستوى في مشروع Xcode. احرص على اختيار نسخ العناصر إلى مجلد المجموعة الوجهة عند مطالبتك بذلك.
6. اختَر مشروعك من "متصفّح المشاريع"، ثم اختَر هدف تطبيقك.
7. افتح علامة التبويب مراحل الإنشاء الخاصة بهدف تطبيقك. في ربط الملف الثنائي بالمكتبات، أضِف أُطر العمل والمكتبات التالية:
   • 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
   • OpenGLES.framework (في حال استخدام OpenGL فقط)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

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

9. لتثبيت حزمة Places SDK for iOS XCFramework، راجِع مقالة البدء باستخدام حزمة Places SDK for iOS.

CocoaPods

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

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

sudo gem install cocoapods

أنشئ Podfile لحزمة تطوير البرامج (SDK) الخاصة بـ "خرائط Google" لنظام التشغيل iOS واستخدِمها لتثبيت واجهة برمجة التطبيقات والملفات التابعة لها:

1. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على جهازك المحلّي. إذا كنت مبتدئًا في تطوير تطبيقات iOS:
   1. أنشِئ مشروعًا جديدًا.
   2. اختَر نموذج iOS > التطبيق.
   3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على مخطط القصة.
      4. اضبط اللغة على Swift أو Objective-C.
2. أنشئ ملفًا باسم Podfile في دليل مشروعك. يحدّد هذا الملف التبعيات الخاصة بمشروعك.
3. عدِّل Podfile وأضِف التبعيات مع إصداراتها. في ما يلي مثال يتضمّن الملحق الذي تحتاج إليه لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لأجهزة iOS:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '10.1.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: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

في الحصول على مفتاح واجهة برمجة تطبيقات، أنشأت مفتاح واجهة برمجة تطبيقات لتطبيقك. والآن، عليك إضافة هذا المفتاح إلى مشروع 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 الخاص بالتطبيق. تفتح حزمة تطوير البرامج (SDK) لتطبيق "خرائط 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 العديد من البرامج التعليمية والتطبيقات النموذجية التي يمكن أن تساعدك في البدء. لمزيد من التفاصيل، راجِع:

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