Membangun aplikasi navigasi iOS sederhana di Swift dengan Navigation SDK Google Maps Platform

1. Sebelum memulai

Codelab ini mengajarkan Anda cara membuat aplikasi iOS sederhana yang menggunakan Google Maps Platform Navigation SDK untuk menavigasi ke tujuan yang telah dikonfigurasi sebelumnya.

Seperti inilah tampilan aplikasi Anda saat selesai.

Prasyarat

• Pengetahuan tentang pengembangan aplikasi iOS dasar di Swift.
• Beberapa pemahaman tentang konsep dasar Google Maps SDK seperti membuat peta yang berpusat pada lokasi tertentu.

Yang akan Anda pelajari

• Cara membuat aplikasi iOS Swift sederhana yang menggunakan Navigation SDK untuk menavigasi ke tujuan.
• Cara mengintegrasikan Navigation SDK dari repositori Cocoapods jarak jauh.
• Cara mengelola izin akses lokasi dan perjanjian pengguna dengan persyaratan pengguna akhir Navigation SDK.
• Cara menginisialisasi SDK.
• Cara menetapkan tujuan dan memulai panduan navigasi.

Yang Anda butuhkan

• Versi stabil XCode terbaru.
• Akun Google dan Project dengan penagihan diaktifkan.
• Perangkat iOS atau perangkat yang diemulasi yang berjalan di XCode Simulator. Apa pun yang Anda pilih, harus memenuhi persyaratan minimum untuk Navigation SDK.

2. Memulai persiapan

Jika Anda belum memiliki akun Google Cloud Platform dan project dengan penagihan diaktifkan, siapkan project Google Cloud Anda dengan mengikuti petunjuk Memulai Google Maps Platform.

Pilih project Google Cloud di konsol

Di Cloud Console, klik menu drop-down project, lalu pilih project yang ingin Anda gunakan untuk codelab ini.

Catatan: Penggunaan Navigation SDK tidak tercakup dalam kredit bulanan berulang Google Maps Platform sebesar $200, tetapi 1.000 tujuan pertama per bulan tidak akan dikenai biaya.

Mengaktifkan Navigation SDK di project Anda

Aktifkan API dan SDK Google Maps Platform yang diperlukan untuk codelab ini di Google Cloud Marketplace.

Buka APIs & Services > Library di Konsol Google Cloud, lalu telusuri "Navigation SDK".

Anda akan melihat satu hasil penelusuran.

Klik Navigation SDK untuk membuka halaman Detail Produk. Klik Enable untuk mengaktifkan SDK di project Anda.

Ulangi proses ini untuk Google Maps SDK for iOS.

Membuat kunci API

Buat kunci API di halaman Kredensial di Cloud Console. Semua permintaan ke Google Maps Platform memerlukan kunci API. Di halaman Credentials di konsol. Klik "+Create Credentials" di bagian atas halaman, lalu pilih "API Key" dari opsi.

Untuk penggunaan produksi, sebaiknya tetapkan pembatasan aplikasi untuk kunci API Anda, tetapi hal ini bersifat opsional untuk codelab ini.

3. Mendapatkan file project contoh

Bagian ini menjelaskan cara menyiapkan project Aplikasi XCode kosong dasar dengan meng-clone file dari repositori GitHub untuk codelab ini. Repo GitHub berisi versi sebelum dan sesudah kode codelab. Codelab akan dimulai dengan template project kosong dan dibangun hingga status selesai. Anda dapat menggunakan project yang telah selesai di repo sebagai referensi jika mengalami kesulitan.

Meng-clone repo atau mendownload kode

Buka direktori tempat Anda ingin menyimpan codelab.

Kemudian, clone repo atau download kode:

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

Jika Anda belum menginstal git, klik tombol ini untuk mendapatkan kode:

Mendapatkan kode

Untuk membantu Anda memulai secepatnya, repositori ini berisi beberapa kode awal di folder Starter untuk membantu Anda mengikuti codelab ini. Ada juga project Solution yang sudah selesai jika Anda ingin langsung melihatnya atau memeriksa progres Anda kapan saja. Untuk menggunakan project solusi, Anda harus mengikuti petunjuk "Instal menggunakan Cocoapods" di bawah, lalu jalankan perintah "pod update" dari folder solution/Navigation SDK Codelab.

Setelah meng-clone repo secara lokal, gunakan XCode untuk membuka folder Starter sebagai project yang sudah ada. Periksa apakah project dibuat dan berjalan.

Catatan: Project untuk codelab ini ditulis di Swift dengan UIKit.

Menghubungkan perangkat atau menyiapkan Simulator XCode

4. Menambahkan Navigation SDK ke aplikasi Anda

Ada tiga cara untuk mengintegrasikan Navigation SDK ke dalam project XCode:codelab ini menggunakan CocoaPods. Untuk mengetahui detail cara mengintegrasikan menggunakan Swift Package Manager, atau menginstal secara manual dengan mendownload SDK, lihat Membuat project Xcode dan menginstal Navigation SDK dalam dokumentasi Navigation SDK.

Menginstal menggunakan Cocoapods

Jika Anda belum memiliki alat CocoaPods, instal di macOS dengan menjalankan perintah berikut dari terminal. Untuk mengetahui detailnya, lihat Panduan Memulai CocoaPods.

sudo gem install cocoapods

Buat file baru bernama Podfile di folder project Anda, di dalam folder starter/Navigation SDK Codelab (di XCode, File > New > File > Other > Empty, simpan sebagai "Podfile")

Tambahkan konten berikut ke Podfile Anda:

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

platform :ios, '15.0'

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

Hemat Podfile.

Buka terminal dan ubah direktori ke lokasi tempat Anda menyimpan Podfile (ini harus berupa folder "starter/Navigation SDK Codelab" di repo codelab)

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

Jalankan perintah pod install. Tindakan ini akan menginstal API yang ditentukan di Podfile, beserta dependensi apa pun

pod install

Tutup Xcode, lalu buka file .xcworkspace project Anda untuk meluncurkan Xcode. Mulai saat ini dan seterusnya, Anda harus menggunakan file .xcworkspace untuk membuka project.

Periksa apakah direktori Pods telah ditambahkan ke struktur project, dan apakah direktori tersebut berisi Pods "GoogleMaps" dan "GoogleNavigation".

Tambahkan kunci API Anda

Tambahkan kunci API ke AppDelegate.swift sebagai berikut:

1. Tambahkan pernyataan impor berikut:

import GoogleMaps
import GoogleNavigation

2. Tambahkan yang berikut ke metode application(_:didFinishLaunchingWithOptions:) Anda:

GMSServices.provideAPIKey("YOUR_API_KEY")

Ganti "YOUR_API_KEY" dengan kunci API yang Anda buat pada langkah sebelumnya.

Buat project Anda dan perbaiki error apa pun.

5. Mengonfigurasi izin aplikasi

Navigation SDK bergantung pada sinyal GPS untuk memberikan lokasi yang disesuaikan dengan jalan dan panduan belokan demi belokan, sehingga aplikasi Anda perlu meminta pengguna untuk memberikan akses ke data lokasi presisi.

Untuk melakukannya, Anda akan menambahkan beberapa properti ke Info.plist aplikasi di Xcode, menambahkan beberapa kode ke aplikasi untuk meminta izin dari pengguna saat runtime, dan menangani error seperti izin tidak diberikan atau lokasi tidak tersedia.

Buka Info.plist di Xcode. Hasilnya akan terlihat seperti ini.

Meminta izin akses lokasi presisi

Anda dapat menambahkan nilai baru dengan mengarahkan kursor ke baris "Daftar Properti Informasi" hingga Anda melihat ikon "+" muncul. Klik "+" untuk melihat dialog dengan nama properti yang disarankan, tetapi perhatikan bahwa Anda juga dapat menambahkan properti secara manual.

Tambahkan properti dan nilai berikut ke Info.plist:

Properti	Nilai
Privasi - Deskripsi Penggunaan Lokasi Selalu dan Saat Digunakan	"Aplikasi ini memerlukan lokasi perangkat Anda untuk memberikan navigasi belokan demi belokan"
Privasi - Deskripsi Penggunaan Lokasi Saat Digunakan	"Aplikasi ini memerlukan lokasi perangkat Anda untuk memberikan navigasi belokan demi belokan"
allowsBackgroundLocationUpdates	YA

Meminta izin akses lokasi latar belakang

Tambahkan properti dan nilai berikut ke Info.plist:

UIBackgroundModes > Tambahkan Baris > Item 0: App registers for location updates (pilih nilai ini dari daftar drop-down saran)

Info.plist akan terlihat seperti ini setelah Anda selesai.

Meminta akses lokasi saat runtime

Tambahkan pernyataan impor berikut ke ViewController.swift:

import GoogleNavigation

Tambahkan deklarasi berikut ke class ViewController Anda:

var locationManager: CLLocationManager!

Tambahkan penggantian metode untuk loadView() dan panggil locationManager.requestAlwaysAuthorization():

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

Aplikasi Anda kini akan meminta lokasi dari pengguna dan menyediakannya untuk aplikasi Anda jika pengguna memberikan izin .

Meminta izin untuk menampilkan notifikasi

Tambahkan kode berikut ke loadView() untuk meminta izin dari pengguna untuk menampilkan notifikasi, yang akan diperlukan untuk menampilkan petunjuk manuver navigasi.

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.")
          }
        }

Bangun dan jalankan aplikasi, lalu periksa apakah Anda diminta untuk membagikan lokasi dan mengaktifkan notifikasi.

6. Menambahkan antarmuka pengguna navigasi

Pada langkah ini, Anda akan menambahkan peta dan mengonfigurasinya untuk menampilkan lokasi. Kemudian, Anda akan menampilkan dialog kepada pengguna dengan persyaratan penggunaan Navigation SDK.

Menambahkan tampilan peta ke aplikasi Anda

Tambahkan baris ini untuk mendeklarasikan variabel GMSMapView di ViewController Anda.

var mapView: GMSMapView!

Tambahkan kode berikut ke loadView() di Viewcontroller.swift Anda untuk melakukan inisialisasi peta.

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

Buat dan jalankan aplikasi Anda, Anda akan melihat peta yang berpusat di London barat daya.

Tips: untuk mendapatkan lintang bujur lain yang akan digunakan sebagai lokasi awal, klik kanan lokasi mana pun di Google Maps di browser, atau tekan lama peta di aplikasi Seluler Google Maps, lalu salin atau catat koordinatnya.

Menampilkan dialog persyaratan penggunaan produk Navigation SDK

Tambahkan kode berikut ke ViewController.swift dalam metode loadView() yang sama dengan kode sebelumnya. Tindakan ini akan menampilkan persyaratan penggunaan pengguna akhir Navigation SDK. Jika tidak diterima, navigasi tidak akan diaktifkan.

// 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.
  }
}

Buat dan jalankan aplikasi untuk melihat dialog.

7. Menambahkan pemroses untuk peristiwa navigasi utama

Langkah ini akan menunjukkan cara menyiapkan pemroses untuk peristiwa utama, seperti kedatangan di tujuan, atau pengemudi yang mengubah rute.

Untuk memproses peristiwa ini, pengontrol tampilan Anda harus mengadopsi protokol GMSNavigatorListener.

Tambahkan protokol ini ke definisi class di ViewController.swift.

class ViewController: UIViewController,
                      GMSNavigatorListener {

Sekarang, tambahkan satu baris kode untuk menyiapkan pemroses di loadView():

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

Terakhir, tambahkan dua metode ke class Anda untuk menangani peristiwa yang dimunculkan.

// 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. Menetapkan tujuan dan memulai panduan

Bagian ini akan mengajarkan cara menetapkan tujuan dan memulai panduan navigasi.

Buat fungsi baru untuk logika navigasi.

Pertama, tambahkan fungsi baru bernama startNav() ke ViewController Anda. Bagian ini akan berisi logika untuk menyetel tujuan dan memulai navigasi.

Catatan: Atribut @objc diperlukan untuk membuat metode tersedia bagi kode Objective-C dan menghindari pemicuan error build setelah Anda menambahkan kode yang memanggil Navigation SDK.

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

Buat Waypoint untuk tujuan.

Selanjutnya, buat array tujuan dengan satu titik jalan di dalamnya.

Tips: Gunakan ID Tempat untuk titik jalan. Dengan menggunakan ID Tempat, Navigation SDK dapat memutuskan lokasi terbaik untuk merutekan ke tujuan. Untuk menemukan ID Tempat, Anda dapat menggunakan aplikasi Place ID Finder atau Google Maps Platform Places API untuk menelusuri tempat.

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

Panggil setDestinations()dan tangani responsnya.

Selanjutnya, panggil setDestinations dan tangani GMSRouteStatus yang ditampilkan.

Jika GMSRouteStatus adalah "OK", mulai panduan dengan menyetel isGuidanceActive=true pada objek navigator mapView. Jika tidak, cetak pernyataan untuk menunjukkan bahwa terjadi error.

Jika nilai GMSRouteStatus yang ditampilkan adalah "OK", mulai simulasikan mengemudi di sepanjang rute dengan memanggil 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
  }
}

Menangani status error umum

Menangani error GMSRouteStatus secara lebih eksplisit akan berguna, terutama saat men-debug masalah awal dengan aplikasi baru Anda. Misalnya, Anda mungkin mendapati bahwa Anda lebih sering mendapatkan error izin lokasi, kunci API, atau "rute tidak ditemukan" pada awalnya karena penyiapan debug, sehingga akan berguna untuk menangani status error ini.

Tambahkan kode yang menangani kasus spesifik ini dan mencetak pernyataan ke konsol.

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
  }

Menambahkan tombol untuk memulai panduan navigasi

Terakhir, tambahkan tombol ke UI dan hubungkan ke metode startNav. Buat metode yang disebut makeButton() dengan kode berikut. Panggil fungsi makeButton() dari 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)
}

Bangun dan jalankan aplikasi Anda.

Catatan: menjalankan kode di

startNav()

akan memanggil

setDestinations()

metode yang menimbulkan biaya setelah 1.000 tujuan pertama digunakan. Lihat Penggunaan dan penagihan untuk mengetahui informasi selengkapnya.

Tips: tetapkan lokasi awal default baru untuk XCode Simulator dengan memilih Features > Location > Custom Location dari menu Simulator, atau tambahkan kode untuk menyimulasikan lokasi dengan Navigation SDK dengan memanggil metode mapview.locationSimulator?.simulateLocationAt() di fungsi startNav().

9. Selamat!

Bagus - Anda telah tiba di tujuan!

Anda telah membuat aplikasi sederhana yang memberikan panduan navigasi belokan demi belokan ke tujuan menggunakan Google Maps Platform Navigation SDK.

Anda telah mengonfigurasi izin aplikasi dan dialog persyaratan pengguna akhir Navigation SDK serta menentukan tujuan menggunakan ID Tempat. Anda telah menangani berbagai status keberhasilan dan error di aplikasi Anda.

10. Manfaatkan lebih jauh

Jika Anda ingin mengembangkan aplikasi lebih lanjut, lihat topik berikut untuk mendapatkan inspirasi.

• Memproses peristiwa navigasi lainnya. Tambahkan kode untuk menampilkan pesan jika waktu atau jarak yang tersisa melebihi nilai minimum.
• Menyesuaikan antarmuka navigasi.
• Jika Anda menginginkan tantangan yang lebih besar, lihat apakah Anda dapat menambahkan pemilih tempat Places API untuk memungkinkan pengguna menetapkan tujuan. Petunjuk: aplikasi demo Navigation SDK memiliki contoh penerapan. Jalankan pod try GoogleNavigation di folder project Anda untuk melihat kode.