إعداد مشروع Xcode

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

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

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

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

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

الخطوة 2: إنشاء مشروع Xcode وتثبيت حزمة تطوير البرامج (SDK) لنظام التنقّل

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

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

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

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

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

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

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

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

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

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

  1. نزِّل ملفات SDK الثنائية وملفات الموارد التالية:
  2. افتح Xcode واختَر إما فتح مشروع حالي أو إنشاء مشروع جديد. إذا كنت مبتدئًا في استخدام نظام التشغيل iOS، أنشئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
  3. أزِل جميع الإشارات الحالية إلى "خرائط Google" و"التنقّل" و"الأماكن" من المشروع.
  4. اسحب حِزم XCFrameworks التالية إلى مشروعك ضمن الإطارات والكتب والملفات المضمّنة لتثبيت حِزم SDK لكل من "خرائط Google" و"التنقّل" (اختَر نسخ العناصر إذا لزم الأمر عندما يُطلب منك ذلك):
    • GoogleMaps.xcframework
    • GoogleNavigation.xcframework
  5. اسحب GoogleMaps.bundle من GoogleMapsResources الذي نزّلته إلى الدليل الأعلى لمشروع Xcode. عند ظهور طلب، تأكَّد من اختيار نسخ العناصر إذا لزم الأمر.
  6. اسحب GoogleNavigation.bundle من GoogleNavigationResources الذي نزّلته إلى الدليل الأعلى لمشروع Xcode. تأكَّد من اختيار نسخ العناصر إلى مجلد المجموعة المقصودة عندما يُطلب منك ذلك.
  7. اختَر مشروعك من "مستكشف المشاريع"، ثم اختَر الهدف المخصّص لتطبيقك.
  8. افتح علامة التبويب مراحل الإنشاء، وفي ربط الثنائي بالمكتبات، أضِف الإطارات والمكتبات التالية:
    • Accelerate.framework
    • AudioToolbox.framework
    • AVFoundation.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
    • Metal.framework
    • OpenGLES.framework
    • QuartzCore.framework
    • Security.framework
    • SystemConfiguration.framework
    • UIKit.framework
    • UserNotifications.framework
    • WebKit.framework
  9. في استهداف تطبيقك، اختَر علامة التبويب الإمكانات، وفعِّل الأوضاع التي تعمل في الخلفية، ثم فعِّل الأوضاع التالية:
    • الصوت وAirPlay و"نافذة ضمن النافذة"
    • تعديلات الموقع الجغرافي
  10. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات البناء. في قسم رموز ربط أخرى، أضِف ‑ObjC لكل من تصحيح الأخطاء والإصدار. إذا لم تكن هذه الإعدادات مرئية، غيِّر الفلتر في عمود إعدادات الإصدار من أساسي إلى الكل.
  11. افتح Info.plist وأضِف أزواج المفتاح/القيمة التالية:
    • المفتاح: NSLocationWhenInUseUsageDescription (الخصوصية - وصف استخدام الموقع الجغرافي أثناء الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي للتنقّل من خلال التوجيهات."
    • المفتاح: NSLocationAlwaysAndWhenInUseUsageDescription (الخصوصية - وصف استخدام الموقع الجغرافي في كل الأوقات وعند الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي للتنقّل من خلال التوجيهات."

CocoaPods

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

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

sudo gem install cocoapods

أنشئ Podfile لحزمة تطوير البرامج Navigation SDK لنظام التشغيل iOS واستخدِم ذلك لتثبيت واجهة برمجة التطبيقات وتبعياتها:

  1. إذا لم يكن لديك مشروع Xcode حتى الآن، أنشئ مشروعًا الآن واحفظه على جهازك. إذا كنت مبتدئًا في تطوير تطبيقات iOS:
    1. أنشئ مشروعًا جديدًا.
    2. اختَر iOS > التطبيق.
    3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على مخطّط القصة.
      4. اضبط اللغة على Swift أو Objective-C.
  2. أنشئ ملفًا باسم Podfile في دليل مشروعك. يحدِّد هذا الملف تبعيات مشروعك.
  3. عدِّل Podfile وأضِف التبعيات مع الإصدارات. في ما يلي مثال يتضمّن التبعيات التي تحتاج إليها لتحميل حزمة تطوير البرامج (SDK) لنظام التشغيل iOS: # Cocoapods install reference # 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GoogleNavigation', '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:

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"];

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

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

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

إذا كنت أحد عملاء "خدمات النقل"

إذا كنت أحد عملاء "خدمات الجوّال"، يمكنك الاطّلاع على معلومات عن الفوترة في مستندات "خدمات الجوّال". لمزيد من المعلومات عن تسجيل المعاملات، يُرجى الاطّلاع على مقالة إعداد الفوترة. للتعرّف على كيفية إضافة أرقام تعريف المعاملات إلى عملية تنفيذ حزمة تطوير البرامج (SDK) لميزة التنقّل، اطّلِع على مقالة ربط استخدام الخدمة بمعاملات "التنقّل".

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

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