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

1. قبل البدء

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

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

7e7c194a98d6dfa4.png

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

ما ستتعلمه

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

المتطلبات

  • أحدث إصدار ثابت من XCode
  • حساب Google ومشروع تم تفعيل الفوترة فيهما
  • جهاز iOS أو جهاز محاكى يعمل في XCode Simulator ويجب أن يستوفي أي منهما الحد الأدنى من متطلبات Navigation SDK.

2. طريقة الإعداد

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

اختيار مشروع على السحابة الإلكترونية في وحدة التحكّم

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

قائمة "اختيار المشروع" المنسدلة في Google Cloud Console

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

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

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

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

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

انقر على Navigation SDK لفتح صفحة التفاصيل. انقر على تفعيل لتفعيل حزمة SDK في مشروعك.

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

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

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

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

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

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

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

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

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

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

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

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

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

توصيل جهاز أو إعداد محاكي XCode

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

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

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

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

sudo gem install cocoapods

أنشئ ملفًا جديدًا باسم Podfile في مجلد مشروعك، داخل مجلد starter/Navigation SDK Codelab (في XCode، انقر على File > New > File > Other > Empty، ثم احفظه باسم "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 إلى بنية المشروع، وأنّه يحتوي على Pods "خرائط Google" و "التنقّل في 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()

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

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

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

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. إضافة واجهة مستخدم للتنقّل

في هذه الخطوة، ستضيف خريطة وتضبطها لعرض موقع جغرافي. بعد ذلك، ستعرض للمستخدم مربّع حوار يتضمّن بنود استخدام Navigation 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

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

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

// 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 المعروضة هي "OK"، ابدأ محاكاة القيادة على طول المسار من خلال استدعاء 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()

طريقة تحمّل رسوم بعد استخدام أول 1,000 وجهة. يمكنك الاطّلاع على مقالة الاستخدام والفوترة لمزيد من المعلومات.

9- تهانينا!

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

7a69dcb75c904d7.png

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

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

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

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

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