إعداد مشروع Xcode

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

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

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

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

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

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

Swift Package Manager

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

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

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

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

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

لإزالة حزمة تطوير البرامج للتنقّل على أجهزة iOS التي تم تثبيتها يدويًا، اتّبِع الخطوات التالية:
  1. من إعدادات ضبط مشروع Xcode، ابحث عن Frameworks, Libraries, and Embedded Content. استخدِم علامة الطرح(-) لإزالة الإطار التالي:
    • 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" و"التنقّل" و"أماكن Google" من المشروع.
  4. اسحب حِزم XCFrameworks التالية إلى مشروعك ضمن Frameworks, Libraries, and Embedded Content لتثبيت كلّ من حِزمتَي تطوير البرامج (SDK) الخاصة بـ "خرائط Google" و"الملاحة" (عندما يُطلب منك ذلك، اختَر Copy items if needed):
    • 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. في هدف تطبيقك، اختَر علامة التبويب القدرات (Capabilities)، فعِّل أوضاع التشغيل في الخلفية (Background Modes)، وفعِّل الأوضاع التالية:
    • الصوت وAirPlay و"نافذة ضمن النافذة"
    • تعديلات على الموقع الجغرافي
  10. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات الإنشاء. في قسم علامات الربط الأخرى، أضِف ‑ObjC لكل من تصحيح الأخطاء والإصدار. إذا لم تظهر هذه الإعدادات، غيِّر الفلتر في شريط إعدادات الإنشاء من أساسي إلى الكل.
  11. افتح Info.plist وأضِف أزواج المفتاح/القيمة التالية:
    • المفتاح: NSLocationWhenInUseUsageDescription (الخصوصية - الموقع الجغرافي أثناء الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي من أجل توفير ميزة التنقّل خطوة بخطوة".
    • المفتاح: NSLocationAlwaysAndWhenInUseUsageDescription (الخصوصية - وصف الاستخدام "الموقع الجغرافي دائمًا وأثناء الاستخدام")
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي من أجل توفير ميزة التنقّل خطوة بخطوة".

CocoaPods

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

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

sudo gem install cocoapods

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

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

platform :ios, '16.0'

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

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

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

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

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

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