يمكنك إنشاء تطبيق تنقل بسيط على نظام iOS في Swift باستخدام حزمة تطوير البرامج (SDK) للتنقّل في "منصة خرائط Google"

1. قبل البدء

يشرح لك هذا الدرس التطبيقي حول الترميز كيفية إنشاء تطبيق iOS بسيط يستخدم حزمة تطوير البرامج (SDK) لميزة التنقّل في "منصة خرائط Google" للانتقال إلى وجهة تم ضبطها مسبقًا.

سيظهر تطبيقك بالشكل التالي عند الانتهاء من إعداده.

7e7c194a98d6dfa4.png

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

ما ستتعرّف عليه

  • كيفية إنشاء تطبيق iOS Swift بسيط يستخدم حزمة تطوير البرامج Navigation SDK للتنقّل إلى وجهة
  • كيفية دمج حزمة SDK للتنقل من مستودع Cocoapods البعيد.
  • كيفية إدارة أذونات تحديد الموقع الجغرافي واتفاقية المستخدم مع بنود المستخدم النهائي لحزمة تطوير البرامج (SDK) للتنقّل
  • كيفية إعداد حزمة تطوير البرامج (SDK)
  • كيفية ضبط وجهة وبدء إرشادات التنقّل

المتطلبات

2. الإعداد

إذا لم يكن لديك حساب على Google Cloud Platform ومشروع تم تفعيل الفوترة فيه، يمكنك إعداد مشروعك على Google Cloud باتّباع تعليمات بدء استخدام "منصة خرائط Google".

اختيار مشروع Google Cloud في وحدة التحكّم

في Cloud Console، انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي تريد استخدامه في هذا الدليل التعليمي.

القائمة المنسدلة لأداة اختيار المشاريع في وحدة التحكّم في Google Cloud.

تفعيل حزمة تطوير البرامج (SDK) للتنقّل في مشروعك

فعِّل واجهات برمجة التطبيقات وحزم تطوير البرامج (SDK) في "منصة خرائط Google" المطلوبة لهذا الدرس التطبيقي حول الترميز في Google Cloud Marketplace.

انتقل إلى واجهات برمجة التطبيقات الخدمات > المكتبة في Google Cloud Console والبحث عن "حزمة SDK الخاصة بالتنقّل"

من المفترض أن تظهر لك نتيجة بحث واحدة.

شاشة "مكتبة واجهات برمجة التطبيقات" في Google Cloud Console، تعرِض صفحة Navigation SDK

انقر على حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لفتح صفحة "تفاصيل المنتج". انقر على تفعيل لتفعيل حزمة تطوير البرامج (SDK) في مشروعك.

كرر هذه العملية لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS.

إنشاء مفتاح واجهة برمجة التطبيقات

أنشئ مفتاح واجهة برمجة التطبيقات في صفحة بيانات الاعتماد في Cloud Console. تتطلب جميع طلبات "منصة خرائط Google" مفتاح واجهة برمجة التطبيقات. في صفحة "بيانات الاعتماد" في وحدة التحكّم. انقر على "+إنشاء بيانات اعتماد" في أعلى الصفحة واختَر "مفتاح واجهة برمجة التطبيقات" من الخيارات.

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

3- الحصول على نماذج ملفات المشروع

يصف هذا القسم كيفية إعداد مشروع تطبيق XCode فارغ من خلال استنساخ الملفات من مستودع جيت هب الخاص بهذا الدرس التطبيقي حول الترميز. يحتوي مستودع جيت هب على الإصدارات السابقة واللاحقة من رمز الدرس التطبيقي حول الترميز. سيبدأ الدرس التطبيقي حول الترميز بنموذج مشروع فارغ وصولاً إلى الحالة النهائية. يمكنك استخدام المشروع النهائي في المستودع كمرجع إذا واجهتك مشكلة.

نسخ مستودع البيانات أو تنزيل الرمز

انتقِل إلى الدليل الذي تريد تخزين ملف codelab فيه.

بعد ذلك، استنسِخ المستودع أو نزِّل الرمز:

git clone https://github.com/googlemaps-samples/codelab-navigation-101-ios-swift

إذا لم يكن git مثبتًا لديك، فانقر فوق هذا الزر للحصول على التعليمة البرمجية:

لمساعدتك في البدء في أسرع وقت ممكن، يحتوي Repo على بعض رموز بدء الاستخدام في مجلد "Starter" لمساعدتك في متابعة هذا الدرس التطبيقي حول الترميز. يتوفّر أيضًا مشروع Solution مكتمل في حال أردت المتابعة أو التحقّق من مستوى تقدّمك في أي وقت. لاستخدام مشروع الحل، عليك اتّباع تعليمات "التثبيت باستخدام Cocoapods" أدناه، ثم تشغيل الأمر "pod update" من مجلد solution/Navigation SDK Codelab.

بعد استنساخ المستودع على الجهاز، استخدِم XCode لفتح مجلد "Starter" كمشروع حالي. تأكَّد من إنشاء المشروع وتشغيله.

توصيل جهاز أو إعداد XCode Simulator

4. إضافة حزمة تطوير البرامج (SDK) لنظام التنقّل إلى تطبيقك

هناك ثلاث طرق لدمج حزمة SDK الخاصة بالتنقّل في مشروع XCode:يستخدم هذا الدرس التطبيقي حول الترميز CocoaPods. لمعرفة تفاصيل عن كيفية الدمج باستخدام أداة Swift Package Manager أو للتثبيت يدويًا من خلال تنزيل حزمة SDK، اطّلِع على إنشاء مشروع Xcode وتثبيت حزمة تطوير البرامج (SDK) لميزة التنقّل باتّجاهات مفصّلة في مستندات حزمة تطوير البرامج (SDK) لميزة التنقّل باتّجاهات مفصّلة.

التثبيت باستخدام Cocoapods

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

sudo gem install cocoapods

أنشئ ملفًا جديدًا باسم Podfile في مجلد مشروعك، داخل مجلد starter/Navigation SDK Codelab (في XCode، ملف > جديد > ملف > غير ذلك > فارغ، احفظ باسم "Podfile").

أضِف المحتوى التالي إلى Podfile:

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'Navigation SDK Codelab' do
  pod 'GoogleNavigation', '9.1.1'
end

وفِّر ‎Podfile.

افتح وحدة تحكّم طرفية وغيِّر الدليل إلى المكان الذي حفظت فيه Podfile (من المفترض أن يكون هذا هو المجلد "starter/Navigation SDK Codelab" في مستودع codelab).

cd "<path-to-starter-project-folder>/Navigation SDK Codelab"

شغِّل الأمر pod install. يؤدي ذلك إلى تثبيت واجهات برمجة التطبيقات المحدّدة في Podfile، بالإضافة إلى أي تبعيات.

pod install

أغلق Xcode، ثم افتح ملف xcworkspace لمشروعك لتشغيل Xcode. من الآن فصاعدًا، يجب عليك استخدام ملف xcworkspace لفتح المشروع.

تأكَّد من إضافة دليل Pods إلى بنية المشروع، وأنّه يحتوي على "GoogleMaps". و"Googleالتنقل" اللوحات

6e81772ee067d452.png

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

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.swift على النحو التالي:

  1. أضف عبارات الاستيراد التالية:
import GoogleMaps
import GoogleNavigation
  1. أضِف ما يلي إلى طريقة application(_:didFinishLaunchingWithOptions:):
GMSServices.provideAPIKey("YOUR_API_KEY")

استبدال "YOUR_API_KEY" باستخدام مفتاح واجهة برمجة التطبيقات الذي أنشأته في الخطوة السابقة

أنشئ مشروعك وأصلِح أي أخطاء.

5- ضبط أذونات التطبيقات

تعتمد حزمة تطوير البرامج (SDK) لميزة التنقّل على إشارات نظام تحديد المواقع العالمي (GPS) لتوفير الموقع الجغرافي المرتبط بالطريق وإرشادات مفصّلة، لذا سيحتاج تطبيقك إلى طلب إذن الوصول إلى بيانات الموقع الجغرافي الدقيق من المستخدم.

ولإجراء ذلك، عليك إضافة بعض السمات إلى ملف Info.plist في Xcode، وإضافة بعض الرموز البرمجية إلى تطبيقك لطلب الإذن من المستخدم في وقت التشغيل، ومعالجة أي أخطاء، مثل عدم منح الإذن أو عدم توفّر الموقع الجغرافي.

افتح Info.plist في Xcode. من المفترض أن يبدو مماثلاً لهذا.

6532a85bd9ac8fb4.png

طلب إذن تحديد الموقع الجغرافي الدقيق

يمكنك إضافة قيم جديدة من خلال تمرير مؤشر الماوس فوق صف "قائمة المواقع الإلكترونية للمعلومات" إلى أن يظهر رمز "+". انقر على رمز "+" لعرض مربع حوار يتضمن أسماء السمات المقترحة، مع ملاحظة أنّه يمكنك أيضًا إضافة الخصائص يدويًا.

أضِف السمات والقيم التالية إلى Info.plist:

الموقع

القيمة

الخصوصية - الموقع الجغرافي دائمًا وعند الاستخدام، وصف الاستخدام

"يتطلّب هذا التطبيق الوصول إلى الموقع الجغرافي لجهازك لتوفير اتّجاهات مفصّلة للتنقّل".

الخصوصية - وصف الموقع الجغرافي أثناء الاستخدام

"يتطلب هذا التطبيق الموقع الجغرافي لجهازك من أجل توفير اتجاهات مفصّلة للتنقّل"

allowsBackgroundLocationUpdates

نعم

طلب إذن رصد الموقع الجغرافي في الخلفية

أضِف السمات والقيم التالية إلى Info.plist:

UIBackgroundModes > إضافة صف > Item 0: App registers for location updates (اختَر هذه القيمة من القائمة المنسدلة للاقتراحات)

من المفترض أن يظهر ملف Info.plist على النحو التالي عند الانتهاء.

3b0c49018451d0ff.png

طلب الوصول إلى الموقع الجغرافي في وقت التشغيل

أضف عبارات الاستيراد التالية إلى ViewController.swift:

import GoogleNavigation

أضِف البيان التالي إلى فئة ViewController:

var locationManager: CLLocationManager!

إضافة إلغاء طريقة loadView() واستدعاء locationManager.requestAlwaysAuthorization():

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

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

طلب الإذن لعرض الإشعارات

أضف الرمز التالي إلى uploadView() لطلب إذن من المستخدم لعرض الإشعارات، والذي سيكون مطلوبًا لعرض إرشادات مناورة التنقل.

UNUserNotificationCenter.current().requestAuthorization(options: [.alert]) {
        granted, error in
        // Handle denied authorization to display notifications.
          if !granted || error != nil {
              print("User rejected request to display notifications.")
          }
        }

أنشِئ التطبيق وشغِّله وتحقَّق من أنّه يُطلب منك مشاركة الموقع الجغرافي وتفعيل الإشعارات.

ad5f665a21170c49.png

6- إضافة واجهة مستخدم للتنقّل

في هذه الخطوة، ستتم إضافة خريطة وإعدادها لعرض الموقع الجغرافي. ستعرض بعد ذلك للمستخدم مربّع حوار يتضمّن بنود استخدام حزمة تطوير البرامج (SDK) للتنقّل.

إضافة عرض خريطة إلى تطبيقك

أضِف هذا السطر للإعلان عن متغيّر GMSMapView في ViewController.

var mapView: GMSMapView!

أضِف الرمز التالي إلى loadView() في Viewcontroller.swift لإعداد الخريطة.

let camera = GMSCameraPosition.camera(withLatitude: 51.483174, longitude: -0.177369, zoom: 14)
let options = GMSMapViewOptions()
options.camera = camera
options.frame = .zero
        
mapView = GMSMapView(options: options)
view = mapView

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

1d46ce5c0851cae3.png

عرض مربّع الحوار لبنود استخدام منتج حزمة تطوير البرامج (SDK) للتنقل

أضِف الرمز التالي إلى ViewController.swift باستخدام طريقة loadView() نفسها المستخدمة في الرمز السابق. سيؤدي ذلك إلى عرض أحكام استخدام Navigation SDK للمستخدم النهائي. في حال عدم الموافقة، لن يتم تفعيل ميزة التنقّل.

// Show the terms and conditions.
let companyName = "Navigation SDK Codelab"
GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(withCompanyName: companyName) { termsAccepted in
  if termsAccepted {
    // Enable navigation if the user accepts the terms.
    self.mapView.isNavigationEnabled = true
    // Request authorization for alert notifications which deliver guidance instructions
    // in the background.
  } else {
    // Handle the case when the user rejects the terms and conditions.
  }
}

أنشئ التطبيق وشغِّله للاطّلاع على مربّع الحوار.

29f17ae5b4c07c9f.png

7- إضافة أدوات استماع لأحداث التنقل الرئيسية

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

للاستماع إلى هذه الأحداث، يجب أن يتّبع عنصر التحكّم في العرض بروتوكول GMSNavigatorListener.

أضِف هذا البروتوكول إلى تعريف الفئة في ViewController.swift.

class ViewController: UIViewController,
                      GMSNavigatorListener {

الآن، أضِف سطرًا من التعليمات البرمجية لإعداد المستمع في loadView():.

// Add a listener for GMSNavigator.
mapView.navigator?.add(self)

وأخيرًا، أضف طريقتين إلى صفك للتعامل مع الأحداث التي يتم طرحها.

// Listener to handle arrival events.
func navigator(_ navigator: GMSNavigator, didArriveAt waypoint: GMSNavigationWaypoint) {
  print("You have arrived at: \(waypoint.title)")
}

// Listener for route change events.
func navigatorDidChangeRoute(_ navigator: GMSNavigator) {
  print("The route has changed.")
}

8. تحديد وجهة وبدء التوجيه

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

إنشاء دالة جديدة لمنطق التنقّل

أولاً، أضِف دالة جديدة باسم startNav() إلى ViewController. سيتضمّن ذلك منطق ضبط وجهة وبدء التنقّل.

// Create a route and start guidance.
@objc func startNav() {
}

إنشاء Waypoint للوجهة.

بعد ذلك، أنشئ صفيفًا من الوجهات يتضمّن نقطة طريق واحدة.

// Create a route and start guidance.
@objc func startNav() {
  var destinations = [GMSNavigationWaypoint]()
  destinations.append(
    GMSNavigationWaypoint.init(
      placeID: "ChIJH-tBOc4EdkgRJ8aJ8P1CUxo",
      title: "Trafalgar Square")!)
}

اتصل برقم setDestinations()وتعامل مع الردّ.

بعد ذلك، اتصل بالرقم setDestinations وتعامل مع GMSRouteStatus الذي يتم إرجاعه.

إذا كانت قيمة GMSRouteStatus هي "حسنًا"، يمكنك بدء التوجيه من خلال ضبط isGuidanceActive=true على عنصر navigator في mapView. أو اطبع عبارة لتوضيح وجود خطأ.

إذا كانت قيمة GMSRouteStatus المعروضة هي "حسنًا"، يمكنك بدء محاكاة القيادة على طول المسار من خلال طلب الرقم mapView.locationSimulator.simulateLocationsAlongExistingRoute().

// Create a route and start guidance.
@objc func startNav() {
  var destinations = [GMSNavigationWaypoint]()
    destinations.append(
      GMSNavigationWaypoint.init(
        placeID: "ChIJH-tBOc4EdkgRJ8aJ8P1CUxo",
          title: "Trafalgar Square")!)
      
  mapView.navigator?.setDestinations(
    destinations
  ) { routeStatus in
    guard routeStatus == .OK else {
      print("Handle route statuses that are not OK.")
      return
    }
    //If routeStatus is OK, start guidance.
    self.mapView.navigator?.isGuidanceActive = true
    //start simulating driving along the route. self.mapView.locationSimulator?.simulateLocationsAlongExistingRoute()
    self.mapView.cameraMode = .following
  }
}

التعامل مع حالات الأخطاء الشائعة

من المفيد التعامل مع أخطاء GMSRouteStatus بشكل أكثر وضوحًا، خاصةً عند تصحيح الأخطاء الأولية في تطبيقك الجديد. على سبيل المثال، قد تجد أنّك حصلت على إذن تحديد الموقع الجغرافي أو مفتاح واجهة برمجة التطبيقات أو رسالة "لم يتم العثور على مسار". الأخطاء بشكل متكرّر في البداية بسبب إعداد تصحيح الأخطاء، لذا قد يكون من المفيد التعامل مع حالات الخطأ هذه.

أضِف رمزًا يعالج هذه الحالات المحدّدة ويطبع بيانًا في وحدة التحكّم.

mapView.navigator?.setDestinations(
  destinations
) { routeStatus in
    guard routeStatus == .OK else {
      print("Handle route statuses that are not OK.")
      switch routeStatus {
       case .locationUnavailable:
        print("Location unavailable.") //check permissions
      case .noRouteFound:
        print("No route found.") //check start location and destination
      case .waypointError:
        print("Waypoint error") //check Place ID
      default:
        print("Not sure what happened")
      }
    return
  }

إضافة زر لبدء إرشادات التنقّل

أخيرًا، أضف زرًا إلى واجهة المستخدم وقم بتوصيله بطريقة startNav. أنشئ طريقة باسم makeButton() باستخدام الرمز البرمجي التالي. استدعاء دالة makeButton() من loadView()

// Add a button to the view.
func makeButton() {
  // A button to start navigation.
  let navButton = UIButton(frame: CGRect(x: 5, y: 150, width: 200, height: 35))
  navButton.backgroundColor = .blue
  navButton.alpha = 0.5
  navButton.setTitle("Start navigation", for: .normal)
  navButton.addTarget(self, action: #selector(startNav), for: .touchUpInside)
  self.mapView.addSubview(navButton)
}

أنشئ تطبيقك وشغِّله.

ملاحظة: تشغيل التعليمة البرمجية في

startNav()

سيتم استدعاء دالة الرسم

setDestinations()

يتم فرض رسوم بعد استخدام أول 1000 وجهة. اطّلِع على الاستخدام والفوترة للحصول على مزيد من المعلومات.

9. تهانينا!

أحسنت - لقد وصلت إلى وجهتك.

7a69dcb75c904d7.png

لقد أنشأت تطبيقًا بسيطًا يقدّم إرشادات حول التنقّل باتجاهات مفصّلة إلى وجهة معيّنة باستخدام حزمة تطوير البرامج (SDK) لميزة التنقّل في "منصّة خرائط Google".

لقد أعددت أذونات التطبيق ومحادثة أحكام المستخدم النهائي لحزمة Navigation SDK وحدّدت وجهة باستخدام رقم تعريف مكان. لقد تعاملت مع حالات النجاح والخطأ المختلفة في تطبيقك.

10. الاستخدام المتقدم

إذا أردت تطوير تطبيقك بشكل أكبر، يمكنك الاطّلاع على المواضيع التالية للحصول على أفكار.

  • الاستماع إلى المزيد من أحداث التنقّل يمكنك إضافة رمز لعرض رسالة إذا تجاوز الوقت أو المسافة المتبقية الحدّ المسموح به.
  • تخصيص واجهة التنقّل
  • إذا كنت ترغب في تحدٍ أكبر، فاطلع على ما إذا كان بإمكانك إضافة منتقي الأماكن في واجهة برمجة تطبيقات الأماكن للسماح للمستخدم بتعيين الوجهة. ملاحظة: تتضمّن التطبيقات التجريبية لحزمة Navigation SDK نموذج تنفيذ. شغِّل pod try GoogleNavigation في مجلد مشروعك للاطّلاع على الرمز.