การเริ่มต้นใช้งาน Driver SDK สําหรับ iOS

Driver SDK คือไลบรารีที่คุณผสานรวมเข้ากับแอปสำหรับคนขับ โดยมีหน้าที่อัปเดต Fleet Engine ด้วยตำแหน่งของคนขับ เส้นทาง ระยะทางที่เหลืออยู่ และเวลาถึงโดยประมาณ นอกจากนี้ยังผสานรวมกับ Navigation SDK ซึ่งให้คำแนะนำในการนำทางแบบเลี้ยวต่อเลี้ยวสำหรับคนขับ

ข้อกำหนดขั้นต่ำของระบบ

ข้อกำหนดเบื้องต้น

คู่มือนี้จะถือว่าแอปของคุณใช้ Navigation SDK และแบ็กเอนด์ Fleet Engine ได้รับการตั้งค่าและพร้อมให้บริการแล้ว อย่างไรก็ตาม โค้ดตัวอย่างจะแสดงตัวอย่างวิธีตั้งค่า Navigation SDK

คุณต้องเปิดใช้ Maps SDK สำหรับ iOS ในโปรเจ็กต์ Google Cloud และรับคีย์ API ด้วย

รับสิทธิ์เข้าถึง

หากคุณเป็นลูกค้า Google Workspace ให้สร้าง Workspace Group เช่น google-maps-platform-sdk-users@workspacedomain.com ในระหว่างการเริ่มต้นใช้งานและระบุชื่อให้ Google ซึ่งเป็นแนวทางที่แนะนำ จากนั้นระบบจะเพิ่มกลุ่ม Workspace ของคุณไปยังรายการที่อนุญาตซึ่งให้สิทธิ์เข้าถึงที่เก็บ CocoaPods ที่ถูกต้อง ยืนยันว่าอีเมลผู้ใช้และอีเมลบัญชีบริการที่ต้องเข้าถึงรวมอยู่ในรายการนี้

หากองค์กรของคุณสร้างกลุ่ม Workspace ไม่ได้ ให้ส่งรายชื่อผู้ใช้และบัญชีบริการที่ต้องเข้าถึงอาร์ติแฟกต์เหล่านี้ไปยัง Google

การพัฒนาในท้องถิ่น

สำหรับการพัฒนาในเครื่อง การเข้าสู่ระบบด้วย Cloud SDK ถือว่าเพียงพอแล้ว

gcloud auth login

อีเมลที่ใช้ลงชื่อเข้าสู่ระบบต้องเป็นสมาชิกของกลุ่ม Workspace

การทำงานอัตโนมัติ (สร้างระบบหรือการผสานรวมอย่างต่อเนื่อง)

ตั้งค่าโฮสต์การทำงานอัตโนมัติตามแนวทางปฏิบัติแนะนำ

• หากกระบวนการทำงานภายในสภาพแวดล้อม Google Cloud ให้ใช้การตรวจหาข้อมูลเข้าสู่ระบบอัตโนมัติ

• หรือเก็บไฟล์คีย์บัญชีบริการไว้ในตำแหน่งที่ปลอดภัยในระบบไฟล์ของโฮสต์และตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS ให้เหมาะสม

อีเมลบัญชีบริการที่เชื่อมโยงกับข้อมูลเข้าสู่ระบบต้องเป็นสมาชิก Workspace Goup

การกำหนดค่าโปรเจ็กต์

คุณกำหนดค่า Driver SDK โดยใช้ CocoaPods ได้

การใช้การให้สิทธิ์และการตรวจสอบสิทธิ์

เมื่อแอปไดรเวอร์สร้างและส่งการอัปเดตไปยังแบ็กเอนด์ Fleet Engine คำขอดังกล่าวต้องมีโทเค็นเพื่อการเข้าถึงที่ถูกต้อง หากต้องการให้สิทธิ์และตรวจสอบสิทธิ์คำขอเหล่านี้ SDK ของไดรเวอร์จะเรียกออบเจ็กต์ของคุณตามโปรโตคอล GMTDAuthorization ออบเจ็กต์มีหน้าที่ระบุโทเค็นเพื่อการเข้าถึงที่จำเป็น

ในฐานะนักพัฒนาแอป คุณสามารถเลือกวิธีสร้างโทเค็นได้ การติดตั้งใช้งานของคุณควรช่วยให้สามารถทำสิ่งต่อไปนี้

• ดึงข้อมูลโทเค็นเพื่อการเข้าถึง ซึ่งอาจอยู่ในรูปแบบ JSON จากเซิร์ฟเวอร์ HTTPS
• แยกวิเคราะห์และแคชโทเค็น
• โปรดรีเฟรชโทเค็นเมื่อหมดอายุ

โปรดดูรายละเอียดของโทเค็นที่เซิร์ฟเวอร์ Fleet Engine คาดหวังที่หัวข้อการสร้างโทเค็นเว็บ JSON (JWT) สำหรับการให้สิทธิ์

รหัสผู้ให้บริการจะเหมือนกับรหัสโปรเจ็กต์ Google Cloud ดูข้อมูลเพิ่มเติมในคู่มือผู้ใช้ Flet Engine Deliveries API

ตัวอย่างต่อไปนี้แสดงการใช้ผู้ให้บริการโทเค็นเพื่อการเข้าถึง

#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

สร้างอินสแตนซ์ DeliveryDriverAPI

หากต้องการอินสแตนซ์ GMTDDeliveryVehicleReporter ก่อนอื่นคุณต้องสร้างอินสแตนซ์ GMTDDeliveryDriverAPI โดยใช้ providerID, vehicleID, driveContext และ accessTokenProvider providerID เหมือนกับรหัสโปรเจ็กต์ Google Cloud คุณจะเข้าถึงอินสแตนซ์ GMTDDeliveryVehicleReporter จาก API ไดรเวอร์ได้โดยตรง

ตัวอย่างต่อไปนี้สร้างอินสแตนซ์ 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];
}

(ไม่บังคับ) ฟังเหตุการณ์ CarReporter

GMTDDeliveryVehicleReporter อัปเดตยานพาหนะเป็นระยะๆ เมื่อ locationTrackingEnabled คือ "ใช่" ในการตอบสนองต่อการอัปเดตเป็นระยะเหล่านี้ ออบเจ็กต์ใดๆ จะติดตามเหตุการณ์ GMTDDeliveryVehicleReporter ได้โดยยึดตามโปรโตคอล GMTDVehicleReporterListener

คุณจัดการกับเหตุการณ์ต่อไปนี้ได้

• vehicleReporter:didSucceedVehicleUpdate

  แจ้งแอปคนขับว่าบริการแบ็กเอนด์ได้รับตำแหน่งยานพาหนะและสถานะอัปเดตเรียบร้อยแล้ว

• vehicleReporter:didFailVehicleUpdate:withError

  แจ้งผู้ฟังว่าการอัปเดตรถไม่สำเร็จ ตราบใดที่มีการเปิดใช้การติดตามตำแหน่ง GMTDDeliveryVehicleReporter จะยังคงส่งข้อมูลล่าสุดไปยังแบ็กเอนด์ Fleet Engine ต่อไป

ตัวอย่างต่อไปนี้จะจัดการกับเหตุการณ์เหล่านี้

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

เปิดใช้การติดตามตำแหน่ง

หากต้องการเปิดใช้การติดตามตำแหน่ง แอปของคุณสามารถตั้งค่า locationTrackingEnabled เป็น YES บน GMTDDeliveryVehicleReporter จากนั้น GMTDDeliveryVehicleReporter จะส่งการอัปเดตตำแหน่งโดยอัตโนมัติ เมื่อ GMSNavigator อยู่ในโหมดการนำทาง (เมื่อตั้งค่าปลายทางผ่าน setDestinations) และตั้งค่า locationTrackingEnabled เป็น YES แล้ว GMTDDeliveryVehicleReporter จะส่งการอัปเดตเส้นทางและเวลาถึงโดยประมาณโดยอัตโนมัติด้วยเช่นกัน

เส้นทางที่ตั้งค่าในระหว่างการอัปเดตดังกล่าวจะเป็นเส้นทางเดียวกับที่คนขับใช้นำทางระหว่างเซสชันการนำทาง ดังนั้น เพื่อให้การติดตามการจัดส่งทำงานได้อย่างถูกต้อง จุดอ้างอิงที่ตั้งค่าไว้ผ่าน -setDestinations:callback: ควรตรงกับปลายทางที่ตั้งค่าไว้ในแบ็กเอนด์ Fleet Engine

ตัวอย่างต่อไปนี้เปิดใช้การติดตามตำแหน่ง

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

โดยค่าเริ่มต้น ช่วงเวลาการรายงานคือ 10 วินาที แต่คุณเปลี่ยนช่วงเวลาการรายงานได้ด้วย locationUpdateInterval ช่วงเวลาการอัปเดตขั้นต่ำที่รองรับ คือ 5 วินาที ช่วงเวลาการอัปเดตสูงสุดที่รองรับคือ 60 วินาที การอัปเดตบ่อยขึ้นอาจทำให้คำขอและข้อผิดพลาดช้าลง

ปิดการอัปเดตตำแหน่ง

แอปปิดใช้การอัปเดตตำแหน่งของรถยนต์ได้ เช่น เมื่อหมดกะของไดรเวอร์ แอปจะตั้งค่า locationTrackingEnabled เป็น NO ได้

  _vehicleReporter.locationTrackingEnabled = NO

จัดการข้อผิดพลาดupdate_mask

เมื่อ GMTDDeliveryVehicleReporter ส่งการอัปเดตรถยนต์ ข้อผิดพลาด update_mask อาจเกิดขึ้นเมื่อหน้ากากว่างเปล่า และโดยปกติจะเกิดขึ้นกับการอัปเดตครั้งแรกหลังจากเริ่มต้นใช้งาน ตัวอย่างต่อไปนี้แสดงวิธีจัดการกับข้อผิดพลาดนี้

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