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 tahmini varış süresi ile güncellemekten sorumludur. Ayrıca, sürücü için adım adım navigasyon talimatları sağlayan Navigasyon SDK'sı ile de entegredir.

Minimum sistem gereksinimleri

Ön koşullar

Bu kılavuzda, uygulamanızın zaten Gezinme SDK'sı uyguladığı ve Fleet Engine arka ucunun ayarlandığı ve kullanılabilir olduğu varsayılır. Ancak örnek kod, Navigasyon SDK'sının nasıl ayarlanacağına dair bir örnek sağlar.

Ayrıca Google Cloud Projenizde iOS için Haritalar SDK'sını etkinleştirmeniz ve 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 bu adı Google'a verin. Önerilen yaklaşım budur. 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 listeye dahil edildiğinden 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ştirme

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

gcloud auth login

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

Otomasyon (sistemler oluşturma 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 sisteminde 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 üyesi olmalıdır.

Proje Yapılandırması

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

Yetkilendirme ve kimlik doğrulamayı uygulama

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

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

• Bir HTTPS sunucusundan büyük olasılıkla JSON biçiminde bir erişim jetonu alın.
• Jetonu ayrıştırıp önbelleğe alın.
• Süresi dolan jetonu yenileyin.

Fleet Engine sunucusunun beklediği jetonların 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ısı 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 kullanarak bir 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 VehicleReporter etkinliklerini dinleyin

locationTrackingEnabled EVET olduğunda GMTDDeliveryVehicleReporter, aracı düzenli olarak günceller. Herhangi bir nesne, bu periyodik güncellemelere yanıt vermek için GMTDVehicleReporterListener protokolüne uyarak GMTDDeliveryVehicleReporter etkinliklerine abone olabilir.

Aşağıdaki etkinlikleri yapabilirsiniz:

• vehicleReporter:didSucceedVehicleUpdate

  Sürücü 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. GMTDDeliveryVehicleReporter, konum izleme etkin olduğu sürece en son verileri Fleet Engine arka ucuna 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ştir

Uygulamanız, konum izlemeyi etkinleştirmek için locationTrackingEnabled hizmetini GMTDDeliveryVehicleReporter sitesinde YES olarak ayarlayabilir. Bu durumda GMTDDeliveryVehicleReporter otomatik olarak konum güncellemesi gönderecektir. GMSNavigator navigasyon modundayken (setDestinations üzerinden bir hedef ayarlandığında) ve locationTrackingEnabled YES olarak ayarlandığında GMTDDeliveryVehicleReporter rota 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 gittiği rota ile aynı olacaktır. Bu nedenle, gönderim takibinin düzgün çalışması için -setDestinations:callback: üzerinden ayarlanan ara nokta, Fleet Engine arka ucunda ayarlanan hedefle eşleşmelidir.

Aşağıdaki örnekte konum izleme etkinleştirilmiştir:

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 yapılan güncellemeler, isteklerin ve hataların daha yavaş olmasına 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ü mesaisi sona erdiğinde uygulamanız locationTrackingEnabled özelliğini NO olarak ayarlayabilir.

  _vehicleReporter.locationTrackingEnabled = NO

update_mask hatalarını işleme

GMTDDeliveryVehicleReporter bir araç güncellemesi gönderdiğinde maske boşken update_mask hatası oluşabilir ve bu genellikle araç başlatıldıktan sonraki ilk güncellemede gerçekleşir. Aşağıdaki örnekte bu hatanın nasıl ele alınacağı 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