إعداد مشروع 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. لا يلزم إجراء أيّ عملية إعداد إضافية.

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، واضغط على مفتاح الإدخال لجلب الحزمة، وانقر على "إضافة حزمة".
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، انتقِل إلى "ملف > الحزم > التحديث إلى أحدث إصدارات الحزم (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 و مساحة العملworkspace في Xcode إذا كنت لا تستخدمها لأي غرض آخر غير 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). في قسم الربط - عام - > علامات الرابط الأخرى ، أضِف -ObjC إلى "تصحيح الأخطاء" و"الإصدار". إذا لم تظهر هذه الإعدادات، غيِّر الفلتر في شريط إعدادات الإصدار (Build Settings) من أساسي (Basic) إلى الكل (All).

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

CocoaPods

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

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

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

sudo gem install cocoapods

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

1. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على جهازك المحلي. إذا كنت جديدًا على تطوير تطبيقات iOS:
   1. أنشئ مشروعًا جديدًا.
   2. اختَر نموذج iOS > تطبيق.
   3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على Storyboard.
      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.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: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

في مقالة الحصول على مفتاح واجهة برمجة تطبيقات، أنشأت مفتاح واجهة برمجة تطبيقات لتطبيقك. والآن، أضِف هذا المفتاح إلى مشروع 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" المتاحة.