Driver SDK — это библиотека, которую вы интегрируете в свое приложение для драйверов. Он отвечает за обновление Fleet Engine с указанием местоположения транспортного средства, маршрута, оставшегося расстояния и расчетного времени прибытия. Он также интегрируется с Navigation SDK, который предоставляет водителю пошаговые инструкции по навигации.
Минимальные системные требования
Предварительные условия
В этом руководстве предполагается, что в вашем приложении уже реализован навигационный SDK , а серверная часть Fleet Engine настроена и доступна. Однако в примере кода представлен образец настройки Navigation SDK .
Вам также необходимо включить Maps SDK для iOS в своем проекте Google Cloud и получить ключ API .
Местное развитие
Для локальной разработки достаточно авторизоваться с помощью Cloud SDK .
gcloud
gcloud auth login
Адрес электронной почты, используемый для входа, должен быть членом группы Workspace.
Автоматизация (создание систем или непрерывная интеграция)
Настройте хосты автоматизации в соответствии с лучшими практиками :
Если ваш процесс выполняется в среде Google Cloud, используйте автоматическое определение учетных данных.
В противном случае сохраните файл ключей сервисного аккаунта в безопасном месте в файловой системе хоста и установите соответствующую переменную среды GOOGLE_APPLICATION_CREDENTIALS .
Адрес электронной почты сервисной учетной записи, связанный с учетными данными, должен быть членом группы рабочей области.
Конфигурация проекта
Менеджер пакетов Swift
Driver SDK можно установить через Swift Package Manager . Чтобы добавить SDK, убедитесь, что вы удалили все существующие зависимости Driver SDK.
Чтобы добавить SDK в новый или существующий проект, выполните следующие действия:
- Откройте
project
илиworkspace
Xcode, затем выберите «Файл» > «Добавить зависимости пакета» . - Введите https://github.com/googlemaps/ios-driver-sdk в качестве URL-адреса, нажмите Enter, чтобы загрузить пакет, и нажмите «Добавить пакет».
- Чтобы установить конкретную
version
, установите в поле «Правило зависимости» один из вариантов на основе версии. Для новых проектов рекомендуем указывать последнюю версию и использовать опцию «Точная версия». После завершения нажмите «Добавить пакет». - В окне «Выбор продуктов пакета» убедитесь, что
GoogleRidesharingDriver
будет добавлен к назначенной вамиmain
цели. После завершения нажмите «Добавить пакет». - Чтобы проверить установку, перейдите на панель
General
» целевой системы. В разделе «Платформы», «Библиотеки» и «Встроенный контент» вы должны увидеть установленные пакеты. Вы также можете просмотреть раздел «Зависимости пакетов» в «Навигаторе проекта», чтобы проверить пакет и его версию.
Чтобы обновить package
для существующего проекта, выполните следующие действия:
Если вы выполняете обновление с версии более ранней, чем 9.0.0, после обновления необходимо удалить следующие зависимости:
GoogleMapsBase
,GoogleMapsCore
иGoogleMapsM4B
. Не удаляйте зависимость дляGoogleMaps
. Дополнительную информацию см. в примечаниях к выпуску версии 9.0.0 .В настройках конфигурации проекта Xcode найдите Frameworks, Libraries и Embedded Content . Используйте знак минус (-), чтобы удалить следующую структуру:
-
GoogleMapsBase
(только для обновлений с версий ранее 9.0.0) -
GoogleMapsCore
(только для обновлений с версий ранее 9.0.0) -
GoogleMapsM4B
(только для обновлений с версий ранее 9.0.0)
-
- В Xcode перейдите в «Файл» > «Пакеты» > «Обновить до последних версий пакетов».
- Чтобы проверить установку, перейдите в раздел «Зависимости пакетов» в «Навигаторе проекта» , чтобы проверить пакет и его версию.
Чтобы удалить существующие зависимости Driver SDK, добавленные с помощью CocoaPods
, выполните следующие действия:
- Закройте рабочую область Xcode. Откройте терминал и выполните следующую команду:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
- Удалите
Podfile
,Podfile.resolved
иworkspace
Xcode, если вы не используете их ни для чего, кроме CocoaPods.
Чтобы удалить существующий Driver SDK, установленный вручную, выполните следующие действия:
В настройках конфигурации проекта Xcode найдите Frameworks, Libraries и Embedded Content . Используйте знак минус
(-)
, чтобы удалить следующую структуру:-
GoogleRidesharingDriver.xcframework
-
Из каталога верхнего уровня вашего проекта Xcode удалите пакет
GoogleRidesharingDriver
.
Какао-стручки
Чтобы настроить Driver SDK с использованием CocoaPods, вам потребуются следующие элементы:
- Инструмент CocoaPods: Чтобы установить этот инструмент, откройте Терминал и выполните следующую команду.
sudo gem install cocoapods
Создайте подфайл для Driver SDK и используйте его для установки API и его зависимостей: Создайте файл с именем Podfile в каталоге вашего проекта. Этот файл определяет зависимости вашего проекта. Отредактируйте подфайл и добавьте свои зависимости. Вот пример, который включает зависимости:
source "https://github.com/CocoaPods/Specs.git" target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GoogleRidesharingDriver' end
Вот пример, который включает модули Alpha и Beta для Driver SDK в качестве зависимостей:
source "https://cpdc-eap.googlesource.com/ridesharing-driver-sdk.git" source "https://github.com/CocoaPods/Specs.git" target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GoogleRidesharingDriver' end
Сохраните подфайл. Откройте терминал и перейдите в каталог, содержащий подфайл:
cd <path-to-project>
Запустите команду установки модуля. При этом будут установлены API, указанные в подфайле, а также все зависимости, которые они могут иметь.
pod install
Закройте Xcode, а затем откройте (дважды щелкните) файл .xcworkspace вашего проекта, чтобы запустить Xcode. С этого момента вы должны использовать файл .xcworkspace для открытия проекта.
Дополнительные сведения см. в руководстве по началу работы с CocoaPods .
Ручная установка
XCFramework — это двоичный пакет, который вы используете для установки Driver SDK. Вы можете использовать этот пакет на нескольких платформах, включая машины, использующие Apple Silicon . В этом руководстве показано, как вручную добавить XCFramework, содержащий Driver SDK, в ваш проект и настроить параметры сборки в Xcode.
Загрузите двоичный файл SDK и ресурсы:
Извлеките файлы, чтобы получить доступ к XCFramework и ресурсам.
Запустите Xcode и либо откройте существующий проект, либо создайте новый проект. Если вы новичок в iOS, создайте новый проект и выберите шаблон приложения iOS.
Создайте группу Frameworks в группе проекта, если она еще не существует.
Чтобы установить Driver SDK, перетащите файл
GoogleRidesharingDriver.xcframework
в свой проект в разделе «Платформы, библиотеки и встроенный контент» . При появлении запроса выберите Копировать элементы, если необходимо.Перетащите загруженный файл
GoogleRidesharingDriver.bundle
в каталог верхнего уровня вашего проекта Xcode. При появлении запроса выберитеCopy items if needed
.Выберите свой проект в Навигаторе проектов и выберите цель своего приложения.
Откройте вкладку «Фазы сборки» и в разделе «Связывание двоичных файлов с библиотеками» добавьте следующие платформы и библиотеки, если они еще не присутствуют:
-
Accelerate.framework
-
AudioToolbox.framework
-
AVFoundation.framework
-
CoreData.framework
-
CoreGraphics.framework
-
CoreLocation.framework
-
CoreTelephony.framework
-
CoreText.framework
-
GLKit.framework
-
ImageIO.framework
-
libc++.tbd
-
libxml2.tbd
-
libz.tbd
-
LocalAuthentication.framework
-
OpenGLES.framework
-
QuartzCore.framework
-
SystemConfiguration.framework
-
UIKit.framework
-
WebKit.framework
-
Выберите свой проект, а не конкретную цель, и откройте вкладку «Настройки сборки» . В разделе «Другие флаги компоновщика» добавьте
-ObjC
как для отладки, так и для выпуска. Если эти настройки не отображаются, измените фильтр на панели «Параметры сборки» с «Базовый» на «Все» .
Проверьте файл манифеста конфиденциальности Apple.
Apple требует предоставить информацию о конфиденциальности для приложений в App Store. Посетите страницу сведений о конфиденциальности Apple App Store для получения обновлений и дополнительной информации.
Файл манифеста конфиденциальности Apple включен в пакет ресурсов для SDK. Чтобы убедиться, что файл манифеста конфиденциальности включен, и проверить его содержимое, создайте архив своего приложения и создайте отчет о конфиденциальности из архива.
Реализация авторизации и аутентификации
Когда ваше приложение для водителей генерирует и отправляет обновления на серверную часть Fleet Engine, запросы должны включать действительные токены доступа. Для авторизации и аутентификации этих запросов Driver SDK вызывает ваш объект в соответствии с протоколом GMTDAuthorization
. Объект отвечает за предоставление необходимого токена доступа.
Как разработчик приложения вы выбираете способ генерации токенов. Ваша реализация должна обеспечивать возможность делать следующее:
- Получите токен доступа, возможно, в формате JSON, с HTTPS-сервера.
- Разберите и кэшируйте токен.
- Обновите токен по истечении срока его действия.
Подробную информацию о токенах, ожидаемых сервером Fleet Engine, см. в разделе Создание веб-токена JSON (JWT) для авторизации .
Идентификатор провайдера совпадает с идентификатором проекта Google Cloud. Дополнительную информацию см. в Руководстве пользователя API доставки Fleet Engine .
В следующем примере реализуется поставщик токенов доступа:
#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
, driverContext
и 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];
}
При необходимости прослушивайте события VehicleReporter.
GMTDDeliveryVehicleReporter
периодически обновляет транспортное средство, если для locationTrackingEnabled
установлено значение YES. Чтобы реагировать на эти периодические обновления, любой объект может подписаться на события 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
также автоматически отправляет обновления маршрута и ETA.
Маршрут, установленный во время этих обновлений, совпадает с маршрутом, по которому движется водитель во время сеанса навигации. Таким образом, чтобы отслеживание автопарка работало правильно, путевая точка, установленная с помощью -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