إعداد مشروع Xcode

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

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

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

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

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

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

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

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

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

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

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

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

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

1. افتح Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة تبعيات الحزمة.
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، ابحث عن الإطارات والكتب المرجعية والمحتوى المضمّن. استخدِم علامة الطرح(-) لإزالة الإطار التالي:

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

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

لإزالة الملحقات الحالية لحزمة تطوير البرامج (SDK) لتطبيق "خرائط 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 يدويًا التي تحتوي على حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لنظام التشغيل iOS إلى مشروعك وضبط إعدادات الإنشاء في Xcode. ‫XCFramework هي حزمة ثنائية يمكنك استخدامها على منصات متعددة، بما في ذلك الأجهزة التي تستخدم شرائح Apple Silicon.

1. نزِّل ملفات SDK الثنائية وملفات الموارد التالية:
   • GoogleMaps
   • GoogleMapsM4B
   • GoogleMapsResources
2. استخرِج الملفات للوصول إلى XCFrameworks والموارد.
3. إذا لم يكن لديك مشروع Xcode حتى الآن، أنشئ مشروعًا الآن واحفظه على جهازك. إذا كنت مبتدئًا في تطوير تطبيقات iOS:
   1. أنشئ مشروعًا جديدًا.
   2. اختَر iOS > التطبيق.
   3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على مخطّط القصة.
      4. اضبط اللغة على Swift أو Objective-C.
4. افتح علامة التبويب عام. اسحب إطار عمل XCFramework التالي إلى مشروعك ضمن الإطارات والمكتبات والمحتوى المضمّن. تأكَّد مما يلي لاختيار عدم التضمين:
   • 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
   • SystemConfiguration.framework
   • UIKit.framework

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

9. لتثبيت حزمة XCFramework الخاصة بحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS، اطّلِع على مقالة البدء باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS.

CocoaPods

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

إذا لم تكن تمتلك أداة 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, '15.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '9.2.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 المستخدَمة في حزمة تطوير البرامج (SDK) لتطبيق "خرائط 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" المتاحة.