ساخت یک برنامه ناوبری ساده iOS در Swift با Google Maps Platform Navigation SDK، ساخت یک برنامه ناوبری ساده iOS در Swift با Google Maps Platform Navigation SDK

۱. قبل از شروع

این آزمایشگاه کد به شما آموزش می‌دهد که یک برنامه iOS ساده بسازید که از SDK ناوبری پلتفرم نقشه‌های گوگل برای پیمایش به یک مقصد از پیش تنظیم‌شده استفاده می‌کند.

این ظاهر برنامه شما پس از اتمام کار خواهد بود.

7e7c194a98d6dfa4.png

پیش‌نیازها

آنچه یاد خواهید گرفت

  • چگونه یک برنامه ساده iOS Swift ایجاد کنیم که از Navigation SDK برای پیمایش به یک مقصد استفاده کند.
  • نحوه ادغام SDK ناوبری از مخزن راه دور Cocoapods.
  • نحوه مدیریت مجوزهای موقعیت مکانی و توافق کاربر با شرایط کاربر نهایی Navigation SDK.
  • نحوه مقداردهی اولیه SDK.
  • نحوه تعیین مقصد و شروع راهنمای ناوبری.

آنچه نیاز دارید

  • آخرین نسخه پایدار XCode.
  • یک حساب گوگل و پروژه با قابلیت پرداخت فعال.
  • یک دستگاه iOS یا یک دستگاه شبیه‌سازی شده که در شبیه‌ساز XCode اجرا می‌شود. هر کدام را که انتخاب کنید، باید حداقل الزامات لازم برای Navigation SDK را داشته باشد.

۲. آماده شوید

اگر از قبل حساب کاربری پلتفرم گوگل کلود و پروژه‌ای با قابلیت پرداخت فعال ندارید، پروژه گوگل کلود خود را طبق دستورالعمل‌های شروع به کار با پلتفرم گوگل مپ راه‌اندازی کنید.

یک پروژه Google Cloud را در کنسول انتخاب کنید

در کنسول ابری ، روی منوی کشویی پروژه کلیک کنید و پروژه‌ای را که می‌خواهید برای این آزمایشگاه کد استفاده کنید، انتخاب کنید.

منوی کشویی انتخابگر پروژه در کنسول گوگل کلود.

فعال کردن SDK ناوبری در پروژه شما

APIها و SDKهای پلتفرم نقشه‌های گوگل مورد نیاز برای این آزمایشگاه کد را در بازار ابری گوگل فعال کنید.

به APIها و خدمات > کتابخانه در کنسول ابری گوگل بروید و عبارت «Navigation SDK» را جستجو کنید.

شما باید یک نتیجه جستجو را ببینید.

صفحه کتابخانه API در کنسول Google Cloud، که صفحه Navigation SDK را نشان می‌دهد.

برای باز کردن صفحه جزئیات محصول، روی گزینه Navigation SDK کلیک کنید. برای فعال کردن SDK در پروژه خود، روی Enable کلیک کنید.

این فرآیند را برای Google Maps SDK برای iOS تکرار کنید.

ایجاد کلید API

یک کلید API در صفحه اعتبارنامه‌های کنسول ابری ایجاد کنید. همه درخواست‌ها به پلتفرم نقشه‌های گوگل نیاز به یک کلید API دارند. در صفحه اعتبارنامه‌ها در کنسول. روی "+ایجاد اعتبارنامه‌ها" در بالای صفحه کلیک کنید و "کلید API" را از گزینه‌ها انتخاب کنید.

برای استفاده در محیط عملیاتی، بهتر است محدودیتی برای کلید API خود تعیین کنید، اما این کار برای این آزمایشگاه کد اختیاری است.

۳. فایل‌های نمونه پروژه را دریافت کنید

این بخش نحوه راه‌اندازی یک پروژه خالی XCode App پایه را با کپی کردن فایل‌های موجود در مخزن GitHub برای این codelab شرح می‌دهد. مخزن Github شامل نسخه‌های قبل و بعد از کد codelab است. codelab با یک الگوی پروژه خالی شروع می‌شود و تا حالت نهایی ادامه می‌یابد. در صورت بروز مشکل، می‌توانید از پروژه نهایی موجود در مخزن به عنوان مرجع استفاده کنید.

مخزن را کلون کنید یا کد را دانلود کنید

به دایرکتوری که می‌خواهید codelab را در آن ذخیره کنید، بروید.

سپس مخزن را کلون کنید یا کد را دانلود کنید:

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

اگر گیت را نصب ندارید، برای دریافت کد روی این دکمه کلیک کنید:

برای شروع هر چه سریع‌تر، این مخزن شامل تعدادی کد اولیه در پوشه Starter است تا به شما در دنبال کردن این codelab کمک کند. همچنین یک پروژه Solution تکمیل‌شده وجود دارد تا در صورت تمایل به ادامه یا بررسی پیشرفت خود در هر زمان، بتوانید از آن استفاده کنید. برای استفاده از پروژه solution، باید دستورالعمل‌های "نصب با استفاده از Cocoapods" را در زیر دنبال کنید و سپس دستور "pod update" را از پوشه solution/Navigation SDK Codelab اجرا کنید.

پس از اینکه مخزن را به صورت محلی کپی کردید، از XCode برای باز کردن پوشه Starter به عنوان یک پروژه موجود استفاده کنید. بررسی کنید که پروژه ساخته و اجرا می‌شود.

اتصال یک دستگاه یا راه‌اندازی شبیه‌ساز XCode

۴. کیت توسعه نرم‌افزار ناوبری (Navigation SDK) را به برنامه خود اضافه کنید

سه راه برای ادغام Navigation SDK در یک پروژه XCode وجود دارد: این codelab از CocoaPods استفاده می‌کند. برای جزئیات بیشتر در مورد نحوه ادغام با استفاده از Swift Package Manager یا نصب دستی با دانلود SDK، به بخش «ایجاد پروژه Xcode و نصب Navigation SDK» در مستندات Navigation SDK مراجعه کنید.

نصب با استفاده از Cocoapods

اگر ابزار CocoaPods را از قبل ندارید، با اجرای دستور زیر از ترمینال، آن را روی macOS نصب کنید. برای جزئیات بیشتر، به راهنمای شروع به کار با 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 را اجرا کنید. این دستور API های مشخص شده در Podfile را به همراه هرگونه وابستگی نصب می کند.

pod install

Xcode را ببندید و سپس فایل .xcworkspace پروژه خود را برای اجرای Xcode باز کنید. از این به بعد، باید از فایل .xcworkspace برای باز کردن پروژه استفاده کنید.

بررسی کنید که دایرکتوری Pods به ساختار پروژه اضافه شده باشد و حاوی Pod های "GoogleMaps" و "GoogleNavigation" باشد.

6e81772ee067d452.png

کلید API خود را اضافه کنید

کلید API خود را به صورت زیر به AppDelegate.swift خود اضافه کنید:

  1. دستورات import زیر را اضافه کنید: 
import GoogleMaps
import GoogleNavigation
  1. کد زیر را به متد application(_:didFinishLaunchingWithOptions:) خود اضافه کنید: 
GMSServices.provideAPIKey("YOUR_API_KEY")

عبارت "YOUR_API_KEY" را با کلید API که در مرحله قبل ایجاد کردید، جایگزین کنید.

پروژه خود را بسازید و هرگونه خطا را برطرف کنید.

۵. مجوزهای برنامه را پیکربندی کنید

کیت توسعه نرم‌افزار ناوبری (Navigation SDK) برای ارائه موقعیت مکانی ثبت‌شده در جاده و راهنمایی گام به گام به سیگنال‌های GPS وابسته است، بنابراین برنامه شما باید از کاربر بخواهد که به داده‌های دقیق موقعیت مکانی دسترسی داشته باشد.

برای انجام این کار، شما باید چند ویژگی به Info.plist برنامه‌های خود در Xcode اضافه کنید، چند کد به برنامه خود اضافه کنید تا در زمان اجرا از کاربر اجازه درخواست کند و هرگونه خطایی مانند عدم اعطای مجوز یا در دسترس نبودن مکان را مدیریت کنید.

فایل Info.plist را در Xcode باز کنید. باید چیزی شبیه به این باشد.

6532a85bd9ac8fb4.png

درخواست مجوز مکان دقیق

می‌توانید با نگه داشتن نشانگر ماوس روی ردیف «فهرست ویژگی‌های اطلاعات» تا زمانی که نماد «+» ظاهر شود، مقادیر جدید اضافه کنید. برای مشاهده کادر محاوره‌ای با نام‌های پیشنهادی ویژگی‌ها، روی «+» کلیک کنید، اما توجه داشته باشید که می‌توانید ویژگی‌ها را به صورت دستی نیز اضافه کنید.

ویژگی‌ها و مقادیر زیر را به Info.plist اضافه کنید:

ملک

ارزش

حریم خصوصی - موقعیت مکانی همیشه و در صورت استفاده توضیحات استفاده

«این برنامه برای ارائه ناوبری گام به گام به موقعیت مکانی دستگاه شما نیاز دارد»

حریم خصوصی - موقعیت مکانی هنگام استفاده توضیحات استفاده

«این برنامه برای ارائه ناوبری گام به گام به موقعیت مکانی دستگاه شما نیاز دارد»

allowBackgroundLocationUpdates را مجاز می‌کند

بله

درخواست مجوز موقعیت مکانی پس‌زمینه

ویژگی‌ها و مقادیر زیر را به Info.plist اضافه کنید:

UIBackgroundModes > Add Row > Item 0: App registers for location updates (این مقدار را از لیست کشویی پیشنهادات انتخاب کنید)

فایل Info.plist پس از اتمام باید چیزی شبیه به این شده باشد.

3b0c49018451d0ff.png

درخواست دسترسی به موقعیت مکانی در زمان اجرا

دستورات import زیر را به ViewController.swift اضافه کنید:

import GoogleNavigation

اعلان زیر را به کلاس ViewController خود اضافه کنید:

var locationManager: CLLocationManager!

یک متد override برای 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

۶. یک رابط کاربری ناوبری اضافه کنید

در این مرحله، یک نقشه اضافه کرده و آن را برای نمایش یک مکان پیکربندی می‌کنید. سپس یک پنجره محاوره‌ای با شرایط استفاده از 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

برنامه خود را بسازید و اجرا کنید، باید نقشه‌ای با محوریت جنوب غربی لندن ببینید.

۱d46ce5c0851cae3.png

نمایش پنجره‌ی شرایط استفاده از محصول Navigation 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

۷. برای رویدادهای ناوبری کلیدی، شنونده اضافه کنید

این مرحله به شما نشان می‌دهد که چگونه می‌توانید شنونده‌هایی را برای رویدادهای کلیدی، مانند رسیدن به مقصد یا تغییر مسیر راننده، تنظیم کنید.

برای گوش دادن به این رویدادها، کنترلر نمای شما باید پروتکل 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.")
}

۸. مقصد را تعیین کنید و هدایت را شروع کنید

این بخش به شما نحوه تعیین مقصد و شروع راهنمای ناوبری را آموزش می‌دهد.

یک تابع جدید برای منطق ناوبری ایجاد کنید.

ابتدا، یک تابع جدید به نام 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 "OK" باشد، با تنظیم 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 ، به خصوص هنگام اشکال‌زدایی مشکلات اولیه برنامه جدیدتان، مفید است. برای مثال، ممکن است متوجه شوید که به دلیل تنظیمات اشکال‌زدایی، در ابتدا خطاهای مجوز مکان، کلید API یا "هیچ مسیری یافت نشد" را بیشتر دریافت می‌کنید، بنابراین مدیریت این حالت‌های خطا می‌تواند مفید باشد.

کدی اضافه کنید که این موارد خاص را مدیریت کند و یک عبارت در کنسول چاپ کند. 

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()

روشی که پس از استفاده از ۱۰۰۰ مقصد اول، هزینه‌ای را در بر می‌گیرد. برای اطلاعات بیشتر به بخش «استفاده و صورتحساب» مراجعه کنید.

۹. تبریک می‌گویم!

آفرین - به مقصد رسیدی!

7a69dcb75c904d7.png

شما یک برنامه ساده ایجاد کرده‌اید که با استفاده از SDK ناوبری پلتفرم نقشه‌های گوگل، راهنمایی ناوبری گام به گام به مقصد ارائه می‌دهد.

شما مجوزهای برنامه و پنجره‌ی شرایط کاربر نهاییِ Navigation SDK را پیکربندی کرده‌اید و با استفاده از یک شناسه‌ی مکان، یک مقصد را مشخص کرده‌اید. حالت‌های مختلف موفقیت و خطا را در برنامه‌ی خود مدیریت کرده‌اید.

۱۰. فراتر رفتن

اگر می‌خواهید توسعه اپلیکیشن خود را بیشتر پیش ببرید، برای الهام گرفتن به مباحث زیر نگاهی بیندازید.

  • منتظر رویدادهای ناوبری بیشتری باشید . کدی اضافه کنید که اگر زمان یا مسافت باقی‌مانده از حد آستانه‌ای بیشتر شد، پیامی نمایش دهد.
  • رابط ناوبری را سفارشی کنید .
  • اگر چالش بزرگ‌تری می‌خواهید، ببینید آیا می‌توانید یک Places API place picker اضافه کنید تا کاربر بتواند مقصد را تعیین کند. نکته: برنامه‌های آزمایشی Navigation SDK یک پیاده‌سازی نمونه دارند. برای دیدن کد، pod try GoogleNavigation در پوشه پروژه خود اجرا کنید.