Memulai Driver SDK untuk iOS

Driver SDK adalah library yang diintegrasikan ke dalam aplikasi driver. Library ini bertanggung jawab untuk mengupdate Fleet Engine dengan lokasi pengemudi, rute, jarak yang tersisa, dan PWT. Alat ini juga terintegrasi dengan Navigation SDK, yang menyediakan petunjuk navigasi belokan demi belokan untuk pengemudi.

Persyaratan sistem minimum

Prasyarat

Panduan ini mengasumsikan bahwa aplikasi Anda sudah mengimplementasikan Navigation SDK dan backend Fleet Engine telah disiapkan dan tersedia. Namun, kode contoh memberikan contoh cara menyiapkan Navigation SDK.

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

Dapatkan akses

Jika Anda adalah pelanggan Google Workspace, buat Grup Workspace seperti google-maps-platform-sdk-users@workspacedomain.com selama aktivasi dan berikan nama kepada Google. Ini adalah pendekatan yang direkomendasikan. Grup Workspace Anda kemudian akan ditambahkan ke daftar yang diizinkan yang memberikan akses ke repositori CocoaPods yang benar. Pastikan bahwa email pengguna dan email akun layanan yang memerlukan akses sudah disertakan dalam daftar ini.

Jika organisasi Anda tidak dapat membuat Grup Workspace, kirim daftar email pengguna dan akun layanan yang memerlukan akses ke artefak ini ke Google.

Pengembangan lokal

Untuk pengembangan lokal, cukup login dengan Cloud SDK.

gcloud auth login

Email yang digunakan untuk login harus merupakan anggota Grup Workspace.

Otomatisasi (sistem build atau continuous integration)

Siapkan host otomatisasi sesuai dengan praktik terbaik:

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

• Jika tidak, simpan file kunci akun layanan di lokasi yang aman pada sistem file host dan tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS dengan tepat.

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

Konfigurasi Project

Anda dapat mengonfigurasi Driver SDK menggunakan CocoaPods.

Mengimplementasikan otorisasi dan autentikasi

Saat aplikasi Driver membuat dan mengirimkan update ke backend Fleet Engine, permintaan tersebut harus menyertakan token akses yang valid. Untuk mengizinkan dan mengautentikasi permintaan ini, Driver SDK memanggil objek Anda yang sesuai dengan protokol GMTDAuthorization. Objek ini bertanggung jawab untuk menyediakan token akses yang diperlukan.

Sebagai developer aplikasi, Anda memilih bagaimana token dihasilkan. Penerapan Anda harus memberikan kemampuan untuk melakukan hal berikut:

• Ambil token akses, yang mungkin dalam format JSON, dari server HTTPS.
• Mengurai dan meng-cache token.
• Muat ulang token saat masa berlakunya habis.

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

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

Contoh berikut mengimplementasikan 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 membuat instance GMTDDeliveryDriverAPI terlebih dahulu menggunakan providerID, vehicleID, driverContext, dan accessTokenProvider. providerID sama dengan project ID Google Cloud. Anda juga dapat mengakses instance GMTDDeliveryVehicleReporter dari driver API secara langsung.

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];
}

Jika perlu, memproses peristiwa VehicleReporter

GMTDDeliveryVehicleReporter memperbarui kendaraan secara berkala jika locationTrackingEnabled YA. Untuk merespons pembaruan berkala ini, setiap objek dapat berlangganan peristiwa GMTDDeliveryVehicleReporter dengan mematuhi protokol GMTDVehicleReporterListener.

Anda dapat menangani peristiwa berikut:

• vehicleReporter:didSucceedVehicleUpdate

  Memberi tahu aplikasi Pengemudi bahwa layanan backend berhasil menerima pembaruan lokasi dan status kendaraan.

• vehicleReporter:didFailVehicleUpdate:withError

  Memberi tahu pemroses bahwa update kendaraan gagal. Selama pelacakan lokasi diaktifkan, GMTDDeliveryVehicleReporter akan terus mengirim 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 di GMTDDeliveryVehicleReporter. Selanjutnya, GMTDDeliveryVehicleReporter akan = otomatis mengirim pembaruan lokasi. Saat GMSNavigator berada dalam mode navigasi (saat tujuan ditetapkan melalui setDestinations) dan locationTrackingEnabled ditetapkan ke YES, GMTDDeliveryVehicleReporter juga akan otomatis mengirim pembaruan rute dan PWT.

Rute yang ditetapkan selama pembaruan tersebut akan menjadi rute yang sama dengan yang dilalui pengemudi selama sesi navigasi. Oleh karena itu, agar pelacakan pengiriman berfungsi dengan benar, titik jalan yang ditetapkan melalui -setDestinations:callback: harus cocok dengan tujuan 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. Update yang lebih sering dapat menyebabkan permintaan dan error yang lebih lambat.

Menonaktifkan pembaruan lokasi

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

  _vehicleReporter.locationTrackingEnabled = NO

Menangani error update_mask

Saat GMTDDeliveryVehicleReporter mengirim update kendaraan, error update_mask dapat terjadi saat mask kosong, dan biasanya terjadi untuk update pertama setelah startup. Contoh berikut menunjukkan cara menangani error ini:

import GoogleRidesharingDriver

class VehicleReporterListener: NSObject, GMTDVehicleReporterListener {
  func vehicleReporter(
    _ vehicleReporter: GMTDVehicleReporter,
    didFail vehicleUpdate: GMTDVehicleUpdate,
    withError error: Error
  ) {
    let fullError = error as NSError
    if let innerError = fullError.userInfo[NSUnderlyingErrorKey] as? NSError {
      let innerFullError = innerError as NSError
      if innerFullError.localizedDescription.contains("update_mask cannot be empty") {
        emptyMaskUpdates += 1
        return
      }
    }
    failedUpdates += 1
  }

  override init() {
    emptyMaskUpdates = 0
    failedUpdates = 0
  }
}

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

@implementation VehicleReporterListener {
  NSInteger emptyMaskUpdates = 0;
  NSInteger failedUpdates = 0;
}

- (void)vehicleReporter:(GMTDVehicleReporter *)vehicleReporter
  didFailVehicleUpdate:(GMTDVehicleUpdate *)vehicleUpdate
             withError:(NSError *)error {
  for (NSError *underlyingError in error.underlyingErrors) {
    if ([underlyingError.localizedDescription containsString:@"update_mask cannot be empty"]) {
      emptyMaskUpdates += 1;
      return;
    }
  }
  failedUpdates += 1
}

@end