إعداد مشروع Xcode

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

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

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

لإنشاء مشروع باستخدام حزمة Navigation SDK لنظام التشغيل iOS، عليك تنزيل ما يلي وتثبيته:

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

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

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

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

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

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

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

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

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

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

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

اتّبِع الخطوات التالية لتثبيت XCFrameworks لحزمة تطوير البرامج Navigation SDK لنظام التشغيل iOS وحزمة تطوير البرامج Maps SDK لنظام التشغيل 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. اختَر مشروعك بدلاً من استهداف محدّد، وافتح علامة التبويب إعدادات البناء. في قسم Other Linker Flags (رموز أخرى لبرنامج الربط)، أضِف ‑ObjC لكل من debug (تصحيح الأخطاء) وrelease (الإصدار). إذا لم تكن هذه الإعدادات مرئية، غيِّر الفلتر في عمود إعدادات التصميم من أساسي إلى الكل.
  11. افتح Info.plist وأضِف أزواج المفتاح/القيمة التالية:
    • المفتاح: NSLocationWhenInUseUsageDescription (الخصوصية - وصف استخدام بيانات الموقع الجغرافي أثناء الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي للتنقّل من خلال التوجيهات."
    • المفتاح: NSLocationAlwaysAndWhenInUseUsageDescription (الخصوصية - وصف استخدام الموقع الجغرافي في كل الأوقات وعند الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي للتنقّل من خلال التوجيهات."

CocoaPods

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

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

sudo gem install cocoapods

أنشئ Podfile لحزمة تطوير البرامج (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. للتأكّد من تضمين ملف بيان الخصوصية وفحص محتوياته، أنشئ أرشيفًا لتطبيقك وأنشئ تقرير خصوصية من الأرشيف.

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

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

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

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