إعداد مشروعك

اتبع هذا الدليل لدمج حزمة SDK للتنقل لنظام التشغيل iOS في أحد تطبيقات iOS.

المتطلبات الأساسية

• قبل البدء في استخدام حزمة SDK للتنقل لنظام التشغيل iOS، تحتاج إلى مشروع به حساب فوترة وتفعيل حزمة SDK لخرائط Google لنظام التشغيل iOS. نقترح إنشاء عدة مالكي مشروعات ومشرفي فوترة، حتى يكون لديك دائمًا شخص لديه هذه الأدوار متاحة لفريقك. لمزيد من المعلومات، راجِع إعداد مشروعك على Google Cloud.
• لإنشاء مشروع باستخدام حزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل iOS، تحتاج إلى الإصدار 15.0 أو إصدار أحدث من Xcode.
• إنّ الحد الأدنى لإصدار نظام التشغيل iOS المستهدف لحزمة تطوير البرامج (SDK) الخاصة بالتنقّل هو 14.0.

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

تثبيت حزمة تطوير البرامج (SDK)

مدير حِزم Swift

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

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

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

1. افتح Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة تبعيات الحزمة.
2. أدخِل https://github.com/googlemaps/ios-navigation-sdk كعنوان URL، واضغط على Enter لسحب الحزمة، ثم انقر على "Add Package".
3. لتثبيت version محدّد، اضبط الحقل قاعدة التبعية على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصحك بتحديد أحدث إصدار واستخدام الخيار "Exact Version". بعد الانتهاء من التعديل، انقر على "Add Package" (إضافة حزمة).
4. من نافذة اختيار منتجات الحزم، تأكَّد من إضافة GoogleNavigation إلى هدف main المحدَّد. بعد الانتهاء من التعديل، انقر على "Add Package" (إضافة حزمة).
5. للتحقّق من التثبيت، انتقِل إلى جزء General المستهدَف. في إطارات الأطر والمكتبات والمحتوى المضمَّن، من المفترض أن تظهر لك الحِزم المثبَّتة. يمكنك أيضًا عرض القسم "تبعيات الحزمة" في "Project Navigator" للتحقق من الحزمة وإصدارها.

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

1. من Xcode، انتقل إلى "ملف > الحزم > التحديث إلى أحدث إصدارات الحزمة".
2. للتحقّق من التثبيت، انتقِل إلى قسم تبعيات الحزمة في Project Navigator للتحقّق من الحزمة وإصدارها.

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

لإزالة العناصر الاعتمادية الحالية لحزمة تطوير البرامج (SDK) الحالية التي تمت إضافتها باستخدام CocoaPods، اتّبِع الخطوات التالية:

1. أغلِق مساحة عمل Xcode. افتح الوحدة الطرفية ونفِّذ الأمر التالي:

   sudo gem install cocoapods-deintegrate cocoapods-clean 
   pod deintegrate 
   pod cache clean --all

2. عليك إزالة Podfile وPodfile.resolved وXcode workspace في حال عدم استخدامها لأي منتج آخر غير CocoaPods.

لإزالة حزمة تطوير البرامج (SDK) الحالية للتنقّل على أجهزة iOS والتي تم تثبيتها يدويًا، اتّبِع الخطوات التالية:

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

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. اضبط واجهة المشروع على Storyboard (لوحة القصة).
      4. اضبط اللغة على Swift أو Objective-C.
2. أنشئ ملفًا باسم Podfile في دليل مشروعك. ويحدد هذا الملف تبعيات مشروعك.
3. عدِّل Podfile وأضِف التبعيات مع versions. في ما يلي مثال يتضمّن التبعية التي تحتاج إليها لحزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل iOS: # مرجع تثبيت Cocoapods #

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleNavigation', '5.3.1'
   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 إلى أحدث إصدار.

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

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

اتّبِع الخطوات التالية لتثبيت XCFrameworks لحزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل iOS وحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS:

1. نزِّل برامج SDK الثنائية وملفات الموارد التالية:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. شغِّل Xcode وافتح مشروعًا حاليًا أو أنشئ مشروعًا جديدًا. إذا كنت مستخدمًا جديدًا لنظام التشغيل iOS، أنشِئ مشروعًا جديدًا واختَر نموذج تطبيق iOS.
3. إزالة جميع مراجع الخرائط والتنقل والأماكن الحالية من المشروع.
   ملاحظة مهمة: لم يتم تضمين حزمة تطوير برامج الأماكن لنظام التشغيل iOS مع حزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل iOS، ويجب تثبيتها بشكل منفصل. وينطبق ذلك بدءًا من الإصدار 5.0 من حزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل iOS. تنصح Google بتنزيل وتثبيت الإصدارات نفسها من حزمة تطوير البرامج (SDK) الخاصة بالأماكن لنظام التشغيل iOS وحزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل iOS. اطّلع على تثبيت حزمة تطوير برامج الأماكن لأجهزة iOS.
4. اسحب عناصر XCFrameworks التالية إلى مشروعك ضمن الأطر والمكتبات والمحتوى المضمَّن لتثبيت كلّ من حزمة تطوير البرامج (SDK) الخاصة بخرائط Google والتنقل (عند مطالبتك، اختَر نسخ العناصر إذا لزم الأمر):
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
   • GoogleNavigation.xcframework
5. اسحب GoogleMaps.bundle من GoogleMapsResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. تأكَّد من اختيار نسخ العناصر إذا لزم الأمر عندما يُطلب منك ذلك.
6. اسحب GoogleNavigation.bundle من GoogleNavigationResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode الخاص بك. تأكَّد من اختيار نسخ العناصر إلى مجلد مجموعة الوجهة عندما يُطلب منك ذلك.
7. اختَر مشروعك من Project Navigator، واختَر هدف تطبيقك.
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 (الخصوصية - وصف استخدام الموقع الجغرافي دائمًا وأثناء الاستخدام)
      القيمة: "يحتاج هذا التطبيق إلى إذن لاستخدام موقعك الجغرافي من أجل التنقّل باتّجاهات مفصّلة".

إضافة ملف بيان الخصوصية في Apple

ملاحظة مهمة: لا تنطبق هذه التعليمات حول ملف بيان الخصوصية في Apple إلا على أحدث إصدار من حزمة تطوير البرامج (SDK).

1. نزِّل حزمة بيان الخصوصية لحزمة تطوير البرامج (SDK) الخاصة بالتنقل لنظام التشغيل iOS: GoogleNavigationPrivacy.
2. استخرِج الملف للوصول إلى GoogleNavigationPrivacy.bundle.
3. أضف GoogleNavigationPrivacy.bundle إلى أداة تصفح مشروع Xcode باستخدام إحدى هذه الطرق. تأكّد من وضع علامة في مربّع "إضافة إلى الاستهدافات" لتحقيق هدف تطبيقك. بعد إضافته، يظهر ملف PrivacyInfo في أداة التنقل في المشروع، ويمكنك فحص القيم.

4. عليك التحقُّق من إضافة بيان الخصوصية من خلال إنشاء أرشيف لتطبيقك وإنشاء تقرير خصوصية منه.

إضافة مفتاح واجهة برمجة التطبيقات إلى مشروعك

توضّح الأمثلة التالية كيفية إضافة مفتاح واجهة برمجة التطبيقات إلى مشروعك في 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"];

إضافة خريطة

يوضّح هذا الرمز كيفية إضافة خريطة بسيطة إلى ViewController حالية، بما في ذلك بعض الإعدادات الأولية للتنقّل.

قبل تمكين التنقل، يجب أن يوافق المستخدم على البنود والشروط. لحثّ المستخدم على الطلب، يُرجى الاتصال بـ GMSNavigationServices.showTermsAndConditionsDialogIfNeeded()، ثم التحقّق لمعرفة ما إذا كان قد تم قبول البنود. إذا رفض المستخدم البنود، لن يكون للسمة mapView.isNavigationEnabled = true أي تأثير، ولن يتم تطبيق mapView.navigator.

Swift

import UIKit
import GoogleNavigation

class ViewController: UIViewController {

  var mapView: GMSMapView!
  var locationManager: CLLocationManager!

  override func loadView() {
    locationManager = CLLocationManager()
    locationManager.requestAlwaysAuthorization()

    let camera = GMSCameraPosition.camera(withLatitude: 47.67, longitude: -122.20, zoom: 14)
    mapView = GMSMapView.map(withFrame: CGRect.zero, camera: camera)

    // Show the terms and conditions.
    let companyName = "Ride Sharing Co."
    GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(
      withCompanyName: companyName) { termsAccepted in
      if termsAccepted {
        // Enable navigation if the user accepts the terms.
        self.mapView.isNavigationEnabled = true
      } else {
        // Handle the case when the user rejects the terms and conditions.
      }
    }

    view = mapView
  }

  // TODO: Add navigation code.

}

Objective-C

#import "ViewController.h"
@import GoogleNavigation;

@interface ViewController ()
@end

@implementation ViewController
GMSMapView *_mapView;
CLLocationManager *_locationManager;

-   (void)loadView {

  _locationManager = [[CLLocationManager alloc] init];
  [_locationManager requestAlwaysAuthorization];

  GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:47.67
                                                          longitude:-122.20
                                                               zoom:14];
  _mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];

  // Show the terms and conditions.
  NSString *companyName = @"Ride Sharing Co.";
  [GMSNavigationServices
    showTermsAndConditionsDialogIfNeededWithCompanyName:companyName
    callback:^(BOOL termsAccepted) {
     if (termsAccepted) {
       // Enable navigation if the user accepts the terms.
       _mapView.navigationEnabled = YES;
     } else {
       // Handle the case when the user rejects the terms and conditions.
     }
   }];

  self.view = _mapView;
}

// TODO: Add navigation code.

@end

شغِّل تطبيقك. من المفترض أن ترى خريطة تتمركز فوق كيركلاند، واشنطن. إذا لم تكن الخريطة مرئية، تأكَّد من تقديم مفتاح واجهة برمجة التطبيقات الصحيح.

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

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