Memulai Driver SDK untuk iOS

Catatan: Kemampuan LMFS menyediakan dua model keamanan untuk digunakan dengan Driver SDK: tidak tepercaya dan tepercaya. Kedua keamanan model menentukan cara aplikasi pengemudi dapat memberikan pembaruan data kendaraan kepada Fleet serta deployment langsung ke App Engine. Model keamanan tidak tepercaya menyediakan lapisan data tambahan memeriksanya dari aplikasi {i>driver<i}. Pada model tidak tepercaya, aplikasi pengemudi hanya dapat mengirim pembaruan lokasi kendaraan langsung ke Fleet serta deployment langsung ke App Engine. Semua pembaruan data kendaraan lainnya dari aplikasi pengemudi yang tidak tepercaya harus dikirim ke backend pelanggan, yang akan menyampaikan data ke Fleet Engine.

Model keamanan tepercaya memungkinkan aplikasi pengemudi mengirim data kendaraan memperbarui langsung ke Fleet Engine, tanpa perlu perantara layanan. Data ini termasuk pembuatan dan pembaruan kendaraan, tugas, dan berhenti.

Model tidak tepercaya tersedia secara umum, sedangkan model driver tepercaya tersedia ada dalam Pratinjau. Untuk mengetahui informasi selengkapnya tentang model driver tepercaya, lihat Peran akun layanan lainnya.

Driver SDK adalah library yang Anda integrasikan ke dalam aplikasi driver. Penting bertanggung jawab untuk memperbarui Fleet Engine dengan lokasi kendaraan, rute, jarak yang tersisa, dan PWT. SDK ini juga terintegrasi dengan Navigation SDK, yang menyediakan petunjuk navigasi belokan demi belokan bagi pengemudi.

Persyaratan sistem minimum

Perangkat seluler harus menjalankan iOS 14 atau nanti.

Xcode versi 15 atau yang lebih baru.

Prasyarat

Panduan ini mengasumsikan bahwa aplikasi Anda telah mengimplementasikan Navigation SDK dan Armada Mesin backend disiapkan dan tersedia. Namun, kode contoh menyediakan sampel cara menyiapkan Navigation SDK.

Anda juga harus mengaktifkan Maps SDK for iOS di Project Google Cloud Anda dan Dapatkan API Kunci.

Pengembangan lokal

Untuk pengembangan lokal, cukup login dengan Cloud SDK.

gcloud

gcloud auth login

Email yang digunakan untuk login harus merupakan anggota Grup Workspace.

Otomatisasi (sistem build atau continuous integration)

Menyiapkan host otomatisasi sesuai dengan praktik terbaik:

• Jika proses Anda berjalan di dalam lingkungan Google Cloud, gunakan otomatis deteksi kredensial.

• Jika tidak, simpan file kunci akun layanan di lokasi yang aman pada sistem file {i>host<i} dan mengatur GOOGLE_APPLICATION_CREDENTIALS variabel lingkungan dengan tepat.

Email akun layanan yang terkait dengan kredensial harus merupakan anggota Grup Workspace.

Konfigurasi Project

Swift Package Manager

Driver SDK dapat diinstal melalui Swift Package Manager. Untuk menambahkan SDK, pastikan Anda memiliki menghapus semua dependensi Driver SDK yang ada.

Penting: Petunjuk ini mengasumsikan penggunaan Xcode 15 atau yang lebih baru, tetapi harus serupa untuk versi Xcode sebelumnya.

Untuk menambahkan SDK ke project baru atau yang sudah ada, ikuti langkah-langkah berikut:

1. Buka project atau workspace Xcode, lalu buka File > Menambahkan Dependensi Paket.
2. Masukkan https://github.com/googlemaps/ios-driver-sdk sebagai URL, tekan Enter untuk menarik paket, dan klik "{i>Add Package<i}".
3. Untuk menginstal version tertentu, setel kolom Dependency Rule ke salah satu opsi berbasis versi. Untuk proyek baru, sebaiknya tentukan versi terbaru dan menggunakan "Versi Persis" sebelumnya. Setelah selesai, klik "Add Package".
4. Dari jendela Choose Package Products, pastikan GoogleRidesharingDriver akan ditambahkan ke target main yang Anda tetapkan. Setelah selesai, klik "Add Package".
5. Untuk memverifikasi penginstalan, buka panel General target Anda. Di Frameworks, Libraries, and Embedded Content, Anda akan melihat paket yang diinstal. Anda juga dapat melihat "{i>Package Dependencies<i}" bagian "Navigator Proyek" untuk memverifikasi paket dan versinya.

Untuk mengupdate package untuk project yang sudah ada, ikuti langkah-langkah berikut:

1. Jika mengupgrade dari versi yang lebih lama dari 9.0.0, Anda harus menghapus dependensi berikut: GoogleMapsBase, GoogleMapsCore, dan GoogleMapsM4B setelah mengupgrade. Jangan hapus dependensi untuk GoogleMaps. Untuk informasi selengkapnya, lihat Catatan Rilis Versi 9.0.0.

   Dari setelan konfigurasi proyek Xcode Anda, temukan Frameworks, Libraries, dan Konten yang Disematkan. Gunakan tanda minus(-) untuk menghapus framework berikut:

   • GoogleMapsBase (Hanya untuk upgrade dari versi sebelum 9.0.0)
   • GoogleMapsCore (Hanya untuk upgrade dari versi sebelum 9.0.0)
   • GoogleMapsM4B (Hanya untuk upgrade dari versi sebelum 9.0.0)
2. Dari Xcode, buka "File > Paket > Update Ke Versi Paket Terbaru".
3. Untuk memverifikasi penginstalan, buka bagian Package Dependencies Project Navigator untuk memverifikasi paket dan versinya.

Penting: Terkadang, artefak tidak dapat diselesaikan atau terjadi error, dalam hal ini pilih "File > Paket > Reset Cache Paket".

Untuk menghapus dependensi Driver SDK yang ada yang ditambahkan menggunakan CocoaPods, ikuti langkah berikut:

1. Tutup ruang kerja Xcode Anda. Buka terminal dan jalankan perintah berikut:

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

2. Hapus Podfile, Podfile.resolved, dan Xcode workspace jika Anda tidak menggunakannya untuk hal apa pun selain CocoaPods.

Untuk menghapus Driver SDK yang sudah diinstal secara manual, ikuti langkah-langkah berikut:

1. Dari setelan konfigurasi project Xcode, temukan Frameworks, Library, dan Konten Tersemat. Gunakan tanda minus(-) untuk menghapus kerangka kerja berikut ini:

   • GoogleRidesharingDriver.xcframework

2. Dari direktori level teratas project Xcode Anda, hapus Paket GoogleRidesharingDriver.

CocoaPods

Untuk mengonfigurasi Driver SDK menggunakan CocoaPods, Anda memerlukan item berikut:

• Alat CocoaPods: Untuk menginstal alat ini, buka Terminal dan jalankan perintah berikut.

   sudo gem install cocoapods

1. Buat Podfile untuk Driver SDK dan gunakan untuk menginstal API dan dependensinya: Buat file bernama Podfile di direktori project Anda. File ini mendefinisikan dependensi project Anda. Edit Podfile dan tambahkan dependensi Anda. Berikut adalah contoh yang menyertakan dependensi:

   source "https://github.com/CocoaPods/Specs.git"
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleRidesharingDriver'
   end
   

   Berikut adalah contoh yang menyertakan pod Alfa dan Beta untuk Driver SDK sebagai dependensi:

   source "https://cpdc-eap.googlesource.com/ridesharing-driver-sdk.git"
   source "https://github.com/CocoaPods/Specs.git"
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleRidesharingDriver'
   end
   

2. Simpan Podfile. Buka terminal dan buka direktori yang berisi Podfile:

   cd <path-to-project>
   

3. Jalankan perintah pod install. Ini akan menginstal API yang ditetapkan dalam Podfile, beserta dependensi apa pun yang mungkin dimilikinya.

   pod install
   

4. Tutup Xcode, lalu buka (klik dua kali) .xcworkspace project Anda untuk meluncurkan Xcode. Mulai saat ini dan seterusnya, Anda harus menggunakan file .xcworkspace untuk membuka proyek.

Catatan: Pastikan Anda menjalankan pod outdated secara berkala untuk mendeteksi saat ada versi SDK yang lebih baru. Untuk informasi selengkapnya, lihat Driver SDK untuk iOS Versi.

Lihat CocoaPods Memulai untuk informasi selengkapnya spesifikasi pendukung.

Penginstalan manual

Perhatian: Sebagai praktik terbaik, gunakan Swift Package Manager atau Cocoapods menginstal SDK Driver setiap kali sebaik mungkin. Sebelum mengikuti panduan ini, pastikan Anda telah mendownload XCFramework.

XCFramework adalah paket biner yang Anda gunakan untuk menginstal Driver SDK. Anda dapat menggunakan paket ini di beberapa platform ini, termasuk komputer yang menggunakan aplikasi Apple silikon. Panduan ini menunjukkan cara menambahkan secara manual XCFramework yang berisi Driver SDK ke project dan mengonfigurasi build Anda di Xcode.

Download resource dan biner SDK:

• GoogleRidesharingDriver.xcframework
• GoogleRidesharingDriver.bundle

Penting: Sebelum menggunakan panduan ini, instal Navigation SDK.

1. Ekstrak file tersebut untuk mengakses XCFramework dan resource.

2. Mulai Xcode dan buka project yang ada, atau buat project baru proyek. Jika Anda baru menggunakan iOS, buat project baru dan pilih Template aplikasi.

3. Buat grup Kerangka Kerja di bawah grup proyek Anda jika belum ada .

4. Untuk menginstal Driver SDK, tarik GoogleRidesharingDriver.xcframework ke project Anda di bagian Framework, Library, dan Konten Tersemat. Saat diminta, pilih Salin item jika perlu.

5. Tarik GoogleRidesharingDriver.bundle yang didownload ke level teratas project Xcode Anda. Saat diminta, pilih Copy items if needed.

6. Pilih proyek Anda dari Navigator Proyek, dan pilih target aplikasi Anda.

7. Buka tab Build Phases, dan di Link Binary with Libraries, tambahkan framework dan library berikut jika belum ada:

   • Accelerate.framework
   • AudioToolbox.framework
   • AVFoundation.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libxml2.tbd
   • libz.tbd
   • LocalAuthentication.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework
   • WebKit.framework

8. Pilih project Anda, bukan target tertentu, dan buka fungsi Build Setelan kami. Di bagian Other Linker Flags, tambahkan -ObjC untuk debug dan rilis. Jika setelan ini tidak terlihat, ubah pada panel Setelan Build dari Dasar ke Semua.

Memeriksa file Manifes Privasi Apple

Apple mewajibkan detail privasi aplikasi untuk aplikasi di App Store. Kunjungi halaman Detail Privasi Apple App Store untuk pembaruan dan informasi selengkapnya.

File Manifes Privasi Apple disertakan dalam paket resource untuk SDK. Untuk memverifikasi bahwa File Manifes Privasi telah disertakan, dan untuk memeriksa kontennya, buat arsip aplikasi dan buat laporan privasi dari arsip.

Menerapkan otorisasi dan autentikasi

Saat aplikasi Driver Anda membuat dan mengirim update ke backend Fleet Engine, permintaan harus menyertakan token akses yang valid. Untuk mengotorisasi dan untuk mengautentikasi permintaan ini, Driver SDK akan memanggil objek yang sesuai dengan GMTDAuthorization dan berperforma tinggi karena merupakan protokol biner. Objek ini bertanggung jawab untuk menyediakan token akses yang diperlukan.

Sebagai developer aplikasi, Anda memilih cara token dibuat. Implementasi Anda harus memberikan kemampuan untuk melakukan hal berikut:

• Ambil token akses, kemungkinan dalam format JSON, dari server HTTPS.
• Uraikan dan simpan token dalam cache.
• Muat ulang token jika masa berlakunya sudah habis.

Untuk detail tentang token yang diharapkan oleh server Fleet Engine, lihat Membuat Token Web JSON (JWT) untuk otorisasi.

ID penyedia sama dengan Project ID Google Cloud. Lihat Panduan Pengguna Fleet Engine Deliveries API untuk informasi selengkapnya.

Contoh berikut menerapkan penyedia token akses:

#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

// SampleAccessTokenProvider.h
@interface SampleAccessTokenProvider : NSObject<GMTDAuthorization>
@end

static NSString *const PROVIDER_URL = @"INSERT_YOUR_TOKEN_PROVIDER_URL";

// SampleAccessTokenProvider.m
@implementation SampleAccessTokenProvider{
  // The cached vehicle token.
  NSString *_cachedVehicleToken;
  // Keep track of the vehicle ID the cached token is for.
  NSString *_lastKnownVehicleID;
  // Keep track of when tokens expire for caching.
  NSTimeInterval _tokenExpiration;
}

- (void)fetchTokenWithContext:(nullable GMTDAuthorizationContext *)authorizationContext
                   completion:(nonnull GMTDAuthTokenFetchCompletionHandler)completion {
  if (!completion) {
    NSAssert(NO, @"%s encountered an unexpected nil completion.", __PRETTY_FUNCTION__);
    return;
  }

  // Get the vehicle ID from the authorizationContext. This is set by the Driver SDK.
  NSString *vehicleID = authorizationContext.vehicleID;
  if (!vehicleID) {
    NSAssert(NO, @"Vehicle ID is missing from authorizationContext.");
    return;
  }

// Clear cached vehicle token if vehicle ID has changed.
  if (![_lastKnownVehicleID isEqual:vehicleID]) {
    _tokenExpiration = 0.0;
    _cachedVehicleToken = nil;
  }
  _lastKnownVehicleID = vehicleID;

  // Clear cached vehicle token if it has expired.
  if ([[NSDate date] timeIntervalSince1970] > _tokenExpiration) {
    _cachedVehicleToken = nil;
  }

  // If appropriate, use the cached token.
  if (_cachedVehicleToken) {
    completion(_cachedVehicleToken, nil);
    return;
  }
  // Otherwise, try to fetch a new token from your server.
  NSURL *requestURL = [NSURL URLWithString:PROVIDER_URL];
  NSMutableURLRequest *request = 
                          [[NSMutableURLRequest alloc] initWithURL:requestURL];
  request.HTTPMethod = @"GET";
  // Replace the following key values with the appropriate keys based on your
  // server's expected response.
  NSString *vehicleTokenKey = @"VEHICLE_TOKEN_KEY";
  NSString *tokenExpirationKey = @"TOKEN_EXPIRATION";
  __weak typeof(self) weakSelf = self;
  void (^handler)(NSData *_Nullable data, NSURLResponse *_Nullable response,
                  NSError *_Nullable error) =
      ^(NSData *_Nullable data, NSURLResponse *_Nullable response, NSError *_Nullable error) {
        typeof(self) strongSelf = weakSelf;
        if (error) {
          completion(nil, error);
          return;
        }

        NSError *JSONError;
        NSMutableDictionary *JSONResponse =
            [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&JSONError];

        if (JSONError) {
          completion(nil, JSONError);
          return;
        } else {
          // Sample code only. No validation logic.
          id expirationData = JSONResponse[tokenExpirationKey];
          if ([expirationData isKindOfClass:[NSNumber class]]) {
            NSTimeInterval expirationTime = ((NSNumber *)expirationData).doubleValue;
            strongSelf->_tokenExpiration = [[NSDate date] timeIntervalSince1970] + expirationTime;
          }
          strongSelf->_cachedVehicleToken = JSONResponse[vehicleTokenKey];
          completion(JSONResponse[vehicleTokenKey], nil);
        }
    };
NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSession *mainQueueURLSession =  
       [NSURLSession  sessionWithConfiguration:config delegate:nil
delegateQueue:[NSOperationQueue mainQueue]];
NSURLSessionDataTask *task = [mainQueueURLSession dataTaskWithRequest:request completionHandler:handler];
[task resume];
}

@end

Membuat instance DeliveryDriverAPI

Untuk mendapatkan instance GMTDDeliveryVehicleReporter, Anda harus terlebih dahulu membuat instance Instance GMTDDeliveryDriverAPI menggunakan providerID, vehicleID, driverContext, dan accessTokenProvider. providerID sama dengan ID Project Google Cloud. Dan Anda dapat mengakses GMTDDeliveryVehicleReporter dari API driver secara langsung.

Catatan: Sebagai pengoptimalan yang dimaksudkan, GMSRoadSnappedLocationProvider mungkin tidak mengirimkan pembaruan lokasi secara terus-menerus jika perangkat tidak dipindahkan sejak pembaruan lokasi. Misalnya, jika pengemudi menunggu tidak ada aktivitas di dalam mobil. Dengan demikian, jika ada situasi saat GMTDDeliveryVehicleReporter ditetapkan sebagai pemroses setelah Anda memanggil startUpdatingLocation di GMSRoadSnappedLocationProvider, Google merekomendasikan agar Anda berhenti dan memulai GMSRoadSnappedLocationProvider untuk memastikan pembaruan lokasi baru telah dikirim.

Contoh berikut membuat instance GMTDDeliveryDriverAPI:

#import "SampleViewController.h"
#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView;
}

- (void)viewDidLoad {
  NSString *vehicleID = @"INSERT_CREATED_VEHICLE_ID";
  SampleAccessTokenProvider *accessTokenProvider = 
                                [[SampleAccessTokenProvider alloc] init];
  GMTDDriverContext *driverContext = 
     [[GMTDDriverContext alloc] initWithAccessTokenProvider:accessTokenProvider
                                                 providerID:PROVIDER_ID 
                                              vehicleID:vehicleID 
      navigator:_mapView.navigator];

  GMTDDeliveryDriverAPI *deliveryDriverAPI = [[GMTDDeliveryDriverAPI alloc] initWithDriverContext:driverContext];
}

Mendengarkan peristiwa VehicleReporter (opsional)

GMTDDeliveryVehicleReporter mengupdate kendaraan secara berkala saat locationTrackingEnabled adalah YA. Untuk menanggapi pembaruan berkala ini, objek dapat berlangganan peristiwa GMTDDeliveryVehicleReporter dengan mematuhi protokol GMTDVehicleReporterListener.

Anda dapat menangani peristiwa berikut:

• vehicleReporter:didSucceedVehicleUpdate

  Memberi tahu aplikasi Driver bahwa layanan backend berhasil menerima lokasi kendaraan dan pembaruan negara bagian.

• vehicleReporter:didFailVehicleUpdate:withError

  Memberi tahu pemroses bahwa update kendaraan gagal. Selama lokasi pelacakan diaktifkan, GMTDDeliveryVehicleReporter akan terus mengirimkan data terbaru ke backend Fleet Engine.

Contoh berikut menangani peristiwa ini:

SampleViewController.h
@interface SampleViewController : UIViewController<GMTDVehicleReporterListener>
@end

SampleViewController.m
#import "SampleViewController.h"
#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView;
}

- (void)viewDidLoad {
  // ASSUMES YOU IMPLEMENTED HAVE THE SAMPLE CODE UP TO THIS STEP.
  [ridesharingDriverAPI.vehicleReporter addListener:self];
}

- (void)vehicleReporter:(GMTDDeliveryVehicleReporter *)vehicleReporter didSucceedVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate {
  // Handle update succeeded.
}

- (void)vehicleReporter:(GMTDDeliveryVehicleReporter *)vehicleReporter didFailVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate withError:(NSError *)error {
  // Handle update failed.
}

@end

Aktifkan pelacakan lokasi

Untuk mengaktifkan pelacakan lokasi, aplikasi Anda dapat menetapkan locationTrackingEnabled ke YES pada GMTDDeliveryVehicleReporter. Setelah itu GMTDDeliveryVehicleReporter otomatis mengirimkan pembaruan lokasi. Saat GMSNavigator sedang melakukan navigasi mode (jika tujuan ditetapkan melalui setDestinations) dan locationTrackingEnabled disetel ke YES, GMTDDeliveryVehicleReporter otomatis mengirimkan pembaruan rute dan PWT juga.

Rute yang ditetapkan selama pembaruan tersebut adalah rute yang sama dengan yang dilalui pengemudi bernavigasi selama sesi navigasi. Sehingga, agar pelacakan perangkat berfungsi dengan benar, titik jalan yang ditetapkan melalui -setDestinations:callback: harus cocok dengan yang ditetapkan di backend Fleet Engine.

Contoh berikut mengaktifkan pelacakan lokasi:

SampleViewController.m
#import "SampleViewController.h"
#import "SampleAccessTokenProvider.h"
#import <GoogleRidesharingDriver/GoogleRidesharingDriver.h>

static NSString *const PROVIDER_ID = @"INSERT_YOUR_PROVIDER_ID";

@implementation SampleViewController {
 GMSMapView *_mapView; 
}

- (void)viewDidLoad {
  // ASSUMES YOU IMPLEMENTED HAVE THE SAMPLE CODE UP TO THIS STEP.
  deliveryDriverAPI.vehicleReporter.locationTrackingEnabled = YES;
}

@end

Secara default, interval pelaporan adalah 10 detik, tetapi interval pelaporan dapat diubah dengan locationUpdateInterval. Interval update minimum yang didukung adalah 5 detik. Interval update maksimum yang didukung adalah 60 detik. Lebih sering update dapat mengakibatkan error dan permintaan yang lebih lambat.

Nonaktifkan pembaruan lokasi dan buat kendaraan offline

Aplikasi Anda dapat menonaktifkan pembaruan lokasi untuk kendaraan. Misalnya, ketika seorang shift pengemudi berakhir, aplikasi Anda dapat menetapkan locationTrackingEnabled ke NO.

  _vehicleReporter.locationTrackingEnabled = NO