Pierwsze kroki z pakietem SDK Driver na iOS

Pakiet Driver SDK to biblioteka zintegrowana z aplikacją sterownika. Jest odpowiada za aktualizację Fleet Engine o lokalizację kierowcy, trasę pozostały dystans i szacowany czas dotarcia na miejsce. Dodatkowo integruje się z pakietem SDK Navigation, który udostępnia kierowcy szczegółowe wskazówki dojazdu.

Minimalne wymagania systemowe

Wymagania wstępne

W tym przewodniku przyjęto założenie, że Twoja aplikacja korzysta już z Navigation SDK oraz Fleet Engine backend jest skonfigurowany i dostępny. Przykładowy kod zawiera jednak przykład konfiguracji Pakiet SDK nawigacji.

Musisz też włączyć Maps SDK na iOS w projekcie Google Cloud i uzyskaj klucz interfejsu API.

Uzyskaj dostęp

Jeśli jesteś klientem Google Workspace, utwórz Grupa Workspace, na przykład google-maps-platform-sdk-users@workspacedomain.com podczas wprowadzenia oraz podać imię i nazwisko firmie Google. To zalecane podejście. Twoja grupa Workspace zostanie dodana do listy dozwolonych, która przyznaje dostęp do prawidłowych repozytoriów CocoaPods. Upewnij się, że użytkownik adresy e-mail oraz adresy e-mail kont usługi, które potrzebują dostępu, są uwzględnione na tej liście.

Jeśli Twoja organizacja nie może tworzyć grup Workspace, wyślij do Google listę adresów e-mail użytkowników i kont usługi, które potrzebują dostępu do tych artefaktów.

Programowanie lokalne

W przypadku programowania lokalnego wystarczy zalogować się za pomocą Pakiet SDK Cloud.

gcloud auth login

Adres e-mail użyty do zalogowania musi należeć do grupy Workspace.

Automatyzacja (tworzenie systemów lub ciągła integracja)

Skonfiguruj hosty automatyzacji zgodnie z sprawdzone metody:

• Jeśli proces działa w środowisku Google Cloud, użyj automatyczne Wykrywanie danych logowania.

• W przeciwnym razie zapisz plik klucza konta usługi w bezpiecznej lokalizacji systemu plików hosta i ustaw parametr GOOGLE_APPLICATION_CREDENTIALS odpowiednio zmiennej środowiskowej.

Adres e-mail konta usługi powiązany z danymi logowania musi należeć do ze strony Google Workspace.

Konfiguracja projektu

Pakiet Driver SDK możesz skonfigurować za pomocą CocoaPods.

Sprawdź plik manifestu prywatności Apple

Apple wymaga podania informacji o ochronie prywatności w aplikacjach z App Store. Aktualizacje i inne informacje znajdziesz na stronie z informacjami o ochronie prywatności w Apple App Store.

Plik manifestu prywatności Apple jest zawarty w pakiecie zasobów SDK. Aby sprawdzić, czy plik manifestu prywatności został dołączony, i sprawdzić jego zawartość, utwórz archiwum aplikacji i wygeneruj raport o ochronie prywatności z archiwum.

Wdrażanie autoryzacji i uwierzytelniania

Gdy aplikacja Driver generuje i wysyła aktualizacje do backendu Fleet Engine, żądania muszą zawierać prawidłowe tokeny dostępu. Aby autoryzować i uwierzytelniają te żądania, pakiet Driver SDK wywołuje obiekt zgodny z GMTDAuthorization protokołu. Obiekt odpowiada za udostępnienie wymaganego tokena dostępu.

Jako deweloper aplikacji możesz wybrać sposób generowania tokenów. Twoja implementacja powinien umożliwiać:

• Pobierz token dostępu, prawdopodobnie w formacie JSON, z serwera HTTPS.
• Przeanalizuj token i zapisz go w pamięci podręcznej.
• Odśwież token po jego wygaśnięciu.

Szczegółowe informacje o tokenach oczekiwanych przez serwer Fleet Engine znajdziesz w sekcji Tworzenie tokena internetowego JSON (JWT) na potrzeby autoryzacji

Identyfikator dostawcy jest taki sam jak identyfikator projektu Google Cloud. Zobacz Przewodnik użytkownika interfejsu Fleet Engine Deliveries API .

Poniższy przykład implementuje dostawcę tokena dostępu:

#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

Tworzenie instancji DeliveryDriverAPI

Aby uzyskać instancję GMTDDeliveryVehicleReporter, musisz najpierw utworzyć instancji GMTDDeliveryDriverAPI za pomocą identyfikatora dostawcy, pojazdID, driveContext i accessTokenProvider. Identyfikator dostawcy jest taki sam jak Identyfikator projektu Google Cloud. Możesz też uzyskać dostęp do usługi GMTDDeliveryVehicleReporter bezpośrednio z interfejsu API sterownika.

Ten przykład tworzy instancję 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];
}

Opcjonalnie możesz nasłuchiwać zdarzeń VehicleReporter

GMTDDeliveryVehicleReporter okresowo aktualizuje pojazd, gdy locationTrackingEnabled – TAK. W odpowiedzi na te okresowe aktualizacje obiekt może subskrybować zdarzenia GMTDDeliveryVehicleReporter przez dostosowanie protokół GMTDVehicleReporterListener.

Możesz obsługiwać te zdarzenia:

• vehicleReporter:didSucceedVehicleUpdate

  Informuje aplikację sterownika, że usługi backendu otrzymały informacje o lokalizacji i stanie pojazdu.

• vehicleReporter:didFailVehicleUpdate:withError

  Informują detektora o niepowodzeniu aktualizacji pojazdu. Dopóki lokalizacja śledzenie jest włączone, GMTDDeliveryVehicleReporter nadal wysyła najnowsze dane do backendu Fleet Engine.

Ten przykład obsługuje te zdarzenia:

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

Włącz śledzenie lokalizacji

Aby włączyć śledzenie lokalizacji, aplikacja może ustawić wartość YES na locationTrackingEnabled w aplikacji GMTDDeliveryVehicleReporter. Zatem GMTDDeliveryVehicleReporter = automatycznie wysyłać aktualizacje lokalizacji. Gdy GMSNavigator jest w trakcie nawigacji (gdy miejsce docelowe jest ustawione za pomocą setDestinations) i Ustawienie locationTrackingEnabled ma wartość YES. GMTDDeliveryVehicleReporter będzie automatycznie wysyłać aktualne informacje o trasie i szacowanym czasie dotarcia na miejsce.

Trasa ustawiona podczas aktualizacji będzie taka sama, jak trasa kierowcy przejście do adresu podczas sesji nawigacji. Dzięki temu śledzenie przesyłek działa punkt pośredni ustawiony przez -setDestinations:callback: powinien być taki sam jak miejsce docelowe ustawione w backendzie Fleet Engine.

Poniższy przykład umożliwia włączenie śledzenia lokalizacji:

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

Domyślny interwał raportowania to 10 sekund, ale interwał raportowania może zostanie zmieniony przez locationUpdateInterval. Minimalny obsługiwany interwał aktualizacji wynosi 5 sekund. Maksymalny obsługiwany interwał aktualizacji to 60 sekund. Częściej mogą spowalniać przesyłanie żądań i błędów.

Wyłącz aktualizacje lokalizacji

Aplikacja może wyłączyć aktualizacje lokalizacji pojazdu. Na przykład, gdy plik kończy się czas zmiany kierowcy, aplikacja może ustawić: locationTrackingEnabled na: NO.

  _vehicleReporter.locationTrackingEnabled = NO

Obsługa błędów update_mask

Gdy GMTDDeliveryVehicleReporter wysyła aktualizację pojazdu, update_mask może wystąpić, gdy maska jest pusta. Zwykle występuje przy pierwszym jego aktualizacja po uruchomieniu. Poniższy przykład pokazuje, jak naprawić ten błąd:

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