iOS için Drive SDK'sını kullanmaya başlama

Sürücü SDK'sı, sürücü uygulamanıza entegre ettiğiniz bir kitaplıktır. Fleet Engine'i sürücünün konumu, rotası, kalan mesafe ve TVS bilgisiyle güncellemekten sorumludur. Ayrıca, sürücü için adım adım navigasyon talimatları sağlayan Navigasyon SDK'sı ile de entegre olur.

Minimum sistem gereksinimleri

Ön koşullar

Bu kılavuzda, uygulamanızın gezinme SDK'sını zaten uyguladığı ve Fleet Engine arka ucunun ayarlanıp kullanılabilir olduğu varsayılmıştır. Ancak bu örnek kod, Gezinme SDK'sının nasıl ayarlanacağına dair bir örnek sunar.

Ayrıca Google Cloud projenizde iOS için Haritalar SDK'sını etkinleştirmeniz ve bir API anahtarı almanız gerekir.

Erişim elde edin

Google Workspace müşterisiyseniz ilk katılım sırasında google-maps-platform-sdk-users@workspacedomain.com gibi bir Workspace Grubu oluşturun ve adı Google'a verin. Bu, önerilen yaklaşımdır. Ardından Workspace Grubunuz, doğru CocoaPods depolarına erişim izni veren bir izin verilenler listesine eklenir. Erişim gerektiren kullanıcı e-postalarının ve hizmet hesabı e-postalarının bu listede bulunduğundan emin olun.

Kuruluşunuz Workspace Grupları oluşturamıyorsa bu yapılara erişmesi gereken kullanıcı ve hizmet hesabı e-postalarının listesini Google'a gönderin.

Yerel gelişim

Yerel geliştirme için Cloud SDK ile giriş yapmanız yeterlidir.

gcloud auth login

Giriş yapmak için kullanılan e-posta adresi, Workspace Grubu'nun bir üyesi olmalıdır.

Otomasyon (sistem derleme veya sürekli entegrasyon)

Otomasyon ana makinelerinizi en iyi uygulamalara göre ayarlayın:

• İşleminiz bir Google Cloud ortamında çalışıyorsa otomatik kimlik bilgisi algılamayı kullanın.

• Aksi takdirde, hizmet hesabı anahtar dosyasını ana makinenin dosya sistemindeki güvenli bir konumda depolayın ve GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini uygun şekilde ayarlayın.

Kimlik bilgileriyle ilişkili hizmet hesabı e-posta adresi, Workspace Goup'ın bir üyesi olmalıdır.

Proje Yapılandırması

Sürücü SDK'sını CocoaPods kullanarak yapılandırabilirsiniz.

Yetkilendirme ve kimlik doğrulamayı uygulama

Sürücü uygulamanız güncellemeleri oluşturup Fleet Engine arka ucuna gönderdiğinde isteklerin geçerli erişim jetonları içermesi gerekir. Sürücü SDK'sı, bu istekleri yetkilendirmek ve doğrulamak için GMTDAuthorization protokolüne uygun şekilde nesnenizi çağırır. Nesne, gerekli erişim jetonunu sağlamaktan sorumludur.

Uygulama geliştirici olarak jetonların nasıl oluşturulacağını siz seçersiniz. Uygulamanız aşağıdakileri yapma imkanı sağlamalıdır:

• Bir HTTPS sunucusundan JSON biçiminde erişim jetonu alın.
• Jetonu ayrıştırıp önbelleğe alın.
• Jetonu süresi dolduğunda yenileyin.

Fleet Engine sunucusu tarafından beklenen jetonlarla ilgili ayrıntılar için Yetkilendirme için JSON Web Jetonu (JWT) oluşturma bölümüne bakın.

Sağlayıcı kimliği, Google Cloud proje kimliği ile aynıdır. Daha fazla bilgi için Fleet Engine Deliveries API Kullanıcı Kılavuzu'na bakın.

Aşağıdaki örnekte bir erişim jetonu sağlayıcı uygulanmaktadır:

#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 örneği oluşturma

GMTDDeliveryVehicleReporter örneği almak için önce providerID, vehicleID, driveContext ve accessTokenProvider özelliklerini kullanarak GMTDDeliveryDriverAPI örneği oluşturmanız gerekir. providerID, Google Cloud proje kimliği ile aynıdır. Ayrıca GMTDDeliveryVehicleReporter örneğine doğrudan sürücü API'sinden erişebilirsiniz.

Aşağıdaki örnek bir GMTDDeliveryDriverAPI örneği oluşturur:

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

İsteğe bağlı olarak Vehicle Reporter etkinliklerini dinleme

locationTrackingEnabled, EVET ise GMTDDeliveryVehicleReporter, aracı düzenli aralıklarla günceller. Bu periyodik güncellemelere yanıt vermek için herhangi bir nesne, GMTDVehicleReporterListener protokolüne uygun olarak GMTDDeliveryVehicleReporter etkinliklerine abone olabilir.

Aşağıdaki etkinlikleri yönetebilirsiniz:

• vehicleReporter:didSucceedVehicleUpdate

  Driver uygulamasına, arka uç hizmetlerinin araç konumu ve durum güncellemesini başarıyla aldığını bildirir.

• vehicleReporter:didFailVehicleUpdate:withError

  Dinleyiciyi bir araç güncellemesinin başarısız olduğu konusunda bilgilendirir. Konum izleme etkin olduğu sürece GMTDDeliveryVehicleReporter, Fleet Engine arka ucuna en yeni verileri göndermeye devam eder.

Aşağıdaki örnekte bu etkinlikler ele alınmaktadır:

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

Konum izlemeyi etkinleştirin

Konum izlemeyi etkinleştirmek için uygulamanız GMTDDeliveryVehicleReporter üzerinde locationTrackingEnabled ayarını YES olarak yapabilir. Bu durumda GMTDDeliveryVehicleReporter, konum güncellemelerini otomatik olarak gönderir. GMSNavigator navigasyon modundayken (setDestinations aracılığıyla hedef ayarlandığında) ve locationTrackingEnabled YES olarak ayarlandığında GMTDDeliveryVehicleReporter, rotayı ve TVS güncellemelerini de otomatik olarak gönderir.

Bu güncellemeler sırasında ayarlanan rota, sürücünün navigasyon oturumu sırasında izlediği rota olacaktır. Bu nedenle, kargo takibinin düzgün çalışması için -setDestinations:callback: ile ayarlanan ara nokta, Fleet Engine arka ucunda ayarlanan hedefle eşleşmelidir.

Aşağıdaki örnek konum izlemeyi etkinleştirir:

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

Varsayılan olarak raporlama aralığı 10 saniyedir ancak raporlama aralığı locationUpdateInterval ile değiştirilebilir. Desteklenen minimum güncelleme aralığı 5 saniyedir. Desteklenen maksimum güncelleme aralığı 60 saniyedir. Daha sık güncelleme yapılması daha yavaş isteklere ve hatalara neden olabilir.

Konum güncellemelerini devre dışı bırak

Uygulamanız bir aracın konum güncellemelerini devre dışı bırakabilir. Örneğin, sürücü vardiyası sona erdiğinde uygulamanız locationTrackingEnabled öğesini NO olarak ayarlayabilir.

  _vehicleReporter.locationTrackingEnabled = NO

güncelleme_mask hatalarını işleme

GMTDDeliveryVehicleReporter bir araç güncellemesi gönderdiğinde maske boşken update_mask hatası oluşabilir ve bu durum genellikle başlatmadan sonraki ilk güncellemede gerçekleşir. Aşağıdaki örnekte bu hatanın nasıl işleneceği gösterilmektedir:

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