Możesz użyć pakietu Driver SDK, aby zapewnić ulepszoną nawigację i śledzenie do aplikacji Podróż i Postęp zamówień. Pakiet Driver SDK zapewnia aktualizacje lokalizacji pojazdów i zadań w rozwiązaniu floty rozwiązań na żądanie w ramach przejazdów i dostaw na żądanie.
Pakiet Driver SDK informuje o usługach Fleet Engine i usługach niestandardowych
lokalizacji i stanu pojazdu. Przykładowo pojazd może być ONLINE
lub OFFLINE
, a lokalizacja pojazdu zmienia się w miarę postępów podróży.
Minimalne wymagania systemowe
Na urządzeniu mobilnym musi być zainstalowany Android 6.0. (poziom interfejsu API 23) lub nowszy.
Konfiguracja kompilacji i zależności
Pakiet SDK sterowników w wersji 4.99 lub nowszej jest dostępny w repozytorium Google Maven.
Gradle
Dodaj do pliku build.gradle
te informacje:
repositories {
...
google()
}
Maven
Dodaj do pliku pom.xml
te informacje:
<project>
...
<repositories>
<repository>
<id>google-maven-repository</id>
<url>https://maven.google.com</url>
</repository>
</repositories>
...
</project>
Konfiguracja projektu
Aby można było używać pakietu Driver SDK, aplikacja musi być kierowana
minSdkVersion
w wersji 23 lub nowszej.
Aby uruchomić aplikację stworzoną za pomocą pakietu Driver SDK, urządzenie musi mieć Usługi Google Play Zainstalowano.
Konfigurowanie projektu programistycznego
Aby skonfigurować projekt programistyczny i uzyskać klucz interfejsu API dla projektu w konsoli Google Cloud:
Utwórz nowy projekt konsoli Google Cloud lub wybierz istniejący projekt, którego chcesz użyć. za pomocą pakietu Driver SDK. Zaczekaj kilka minut do nowy projekt będzie widoczny w konsoli Google Cloud.
Aby można było uruchomić aplikację w wersji demonstracyjnej, projekt musi mieć dostęp do pakietu SDK Maps na Androida. W konsoli Google Cloud wybierz Interfejsy API Usługi > Library, a następnie wyszukaj i włącz pakiet SDK Maps dla na urządzeniu z Androidem.
Wybierz, aby pobrać klucz interfejsu API dla projektu Interfejsy API Usługi > Dane logowania > Utwórz dane logowania > API. Więcej informacji o uzyskiwaniu klucza interfejsu API znajdziesz w artykule Uzyskaj klucz interfejsu API.
Dodaj pakiet Driver SDK do aplikacji
Pakiet Driver SDK jest dostępny w repozytorium Google Maven. repozytorium zawiera pliki .pom (Project Object Model) pakietu SDK i dokumenty Javadocs. Aby dodać pakiet Driver SDK do aplikacji:
Dodaj poniższą zależność do konfiguracji Gradle lub Maven, zastępując Obiekt zastępczy
VERSION_NUMBER
, który wskazuje odpowiednią wersję pakietu Driver SDK.Gradle
Dodaj do
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER' }
Maven
Dodaj do
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-driver</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Pakiet Driver SDK korzysta z pakietu Navigation SDK. Ta zależność jest skonfigurowana w takim jeśli potrzebna jest konkretna wersja Navigation SDK, musi być jawnie zdefiniowane w pliku konfiguracji kompilacji w ten sposób: Pominięcie wspomnianego bloku kodu sprawi, że projekt będzie zawsze pobierany najnowszą wersję pakietu Navigation SDK w głównej wersji produkcyjnej. Pamiętaj, że połączone zachowania najnowszych wersji pakietu Driver SDK oraz Pakiet Navigation SDK został rygorystycznie przetestowany przed opublikowaniem.
Uporządkuj konfigurację zależności w środowisku programistycznym i wersji z odpowiednimi środowiskami.
Gradle
Dodaj do
build.gradle
:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:5.0.0' }
Maven
Dodaj do
pom.xml
:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>5.0.0</version> </dependency> </dependencies>
Dodawanie klucza interfejsu API do aplikacji
Po dodaniu do aplikacji pakietu Driver SDK dodaj do niej klucz interfejsu API. Ty musi używać klucza interfejsu API projektu uzyskanego podczas skonfigurować projekt programistyczny.
W tej sekcji opisano, jak przechowywać klucz interfejsu API w celu zwiększenia jego bezpieczeństwa
przywoływanych przez aplikację. Nie sprawdzaj klucza interfejsu API w swojej wersji
systemu sterowania. Powinien on być zapisany w pliku local.properties
, który jest
znajduje się w katalogu głównym projektu. Więcej informacji na temat
local.properties
, patrz
Pliki właściwości Gradle.
Aby uprościć to zadanie, możesz skorzystać z Wtyczka Gradle obiektów tajnych na Androida.
Aby zainstalować wtyczkę i zapisać klucz interfejsu API:
Otwórz plik
build.gradle
na poziomie głównym i dodaj ten kod do sekcjidependencies
w kolumniebuildscript
.Zakręcony
buildscript { dependencies { // ... classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0" } }
Kotlin
buildscript { dependencies { // ... classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0") } }
Otwórz plik
build.gradle
na poziomie aplikacji i dodaj ten kod do sekcjiplugins
.Zakręcony
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
Kotlin
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
Jeśli używasz Androida Studio, zsynchronizować projekt z Gradle.
Otwórz
local.properties
w katalogu na poziomie projektu i dodaj do tego kodu. ZastąpYOUR_API_KEY
swoim kluczem interfejsu API.MAPS_API_KEY=YOUR_API_KEY
W pliku
AndroidManifest.xml
przejdź do sekcjicom.google.android.geo.API_KEY
i zaktualizuj atrybutandroid:value
w następujący sposób:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Ten przykład zawiera pełny plik manifestu przykładowej aplikacji:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.driverapidemo">
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:supportsRtl="true"
android:theme="@style/_AppTheme">
<meta-data
android:name="com.google.android.geo.API_KEY"
android:value="${MAPS_API_KEY}" />
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
</manifest>
Umieść w aplikacji wymagane informacje o źródłach
Jeśli w swojej aplikacji używasz pakietu Driver SDK, musisz dodać teksty informacji o źródle i licencje open source jako część informacji prawnych dotyczących aplikacji. . Informacje o autorach najlepiej jest dodawać jako niezależną pozycję menu lub jako w menu Informacje.
Informacje o licencjach można znaleźć w pliku „third_party_licenses.txt”. zapisz w niezarchiwizowanego pliku AAR.
Wejdź na https://developers.google.com/android/guides/opensource. jak uwzględniać powiadomienia open source.
Zależności
Jeśli używasz ProGuard do zoptymalizować kompilacje, być może trzeba będzie dodać do ProGuard te wiersze: plik konfiguracyjny:
-dontwarn com.google.**
-dontwarn okio.**
Minimalny obsługiwany poziom interfejsu API to 23.
Inicjowanie pakietu SDK
Identyfikator dostawcy (zwykle identyfikator projektu Google Cloud) jest wymagany do
zainicjować obiekt DriverContext
. Więcej informacji o konfigurowaniu
Projekt Google Cloud, zobacz
Authentication and Authorization (Uwierzytelnianie i autoryzacja).
Zanim zaczniesz używać pakietu Driver SDK, musisz najpierw zainicjować pakiet SDK do nawigacji. Aby zainicjować pakiet SDK:
Uzyskaj obiekt
Navigator
zNavigationApi
.Java
NavigationApi.getNavigator( this, // Activity new NavigationApi.NavigatorListener() { @Override public void onNavigatorReady(Navigator navigator) { // Keep a reference to the Navigator (used to configure and start nav) this.navigator = navigator; } } );
Kotlin
NavigationApi.getNavigator( this, // Activity object : NavigatorListener() { override fun onNavigatorReady(navigator: Navigator) { // Keep a reference to the Navigator (used to configure and start nav) this@myActivity.navigator = navigator } }, )
Utwórz obiekt
DriverContext
, wypełniając wymagane pola.Java
DriverContext driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider( NavigationApi.getRoadSnappedLocationProvider(application)) .build();
Kotlin
val driverContext = DriverContext.builder(application) .setProviderId(providerId) .setVehicleId(vehicleId) .setAuthTokenFactory(authTokenFactory) .setNavigator(navigator) .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(application)) .build()
Zainicjuj obiekt
*DriverApi
za pomocą obiektuDriverContext
.Java
RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
Kotlin
val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
Uzyskaj
RidesharingVehicleReporter
z obiektu interfejsu API. (*VehicleReporter
przedłuża się oNavigationVehicleReporter
).Java
RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();
Kotlin
val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()
Uwierzytelnianie w sieci AuthTokenFactory
Gdy pakiet Driver SDK generuje aktualizacje lokalizacji,
musi wysyłać te aktualizacje do
z serwera Fleet Engine. Aby uwierzytelniać te żądania,
Pakiet SDK sterownika będzie wywoływać podany element wywołujący
wystąpienia AuthTokenFactory
.
Za generowanie tokenów uwierzytelniania w lokalizacji odpowiada fabryka
godzinę aktualizacji.
Sposób generowania tokenów zależy od sytuacji danego dewelopera. Implementacja będzie jednak prawdopodobnie musiała:
- pobranie tokena uwierzytelniania, prawdopodobnie w formacie JSON, z serwera HTTPS
- przeanalizować token i przechowywać go w pamięci podręcznej
- odświeżaj 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
Oto szkieletowa implementacja elementu AuthTokenFactory
:
Java
class JsonAuthTokenFactory implements AuthTokenFactory {
private String token; // initially null
private long expiryTimeMs = 0;
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
@Override
public String getToken(AuthTokenContext authTokenContext) {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId());
}
return token;
}
private void fetchNewToken(String vehicleId) {
String url =
new Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString();
try (Reader r = new InputStreamReader(new URL(url).openStream())) {
com.google.gson.JsonObject obj
= com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
token = obj.get("Token").getAsString();
expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();
// The expiry time could be an hour from now, but just to try and avoid
// passing expired tokens, we subtract 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000;
} catch (IOException e) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw new RuntimeException("Could not get auth token", e);
}
}
}
Kotlin
class JsonAuthTokenFactory : AuthTokenFactory() {
private var token: String = ""
private var expiryTimeMs: Long = 0
// This method is called on a thread whose only responsibility is to send
// location updates. Blocking is OK, but just know that no location updates
// can occur until this method returns.
override fun getToken(context: AuthTokenContext): String {
if (System.currentTimeMillis() > expiryTimeMs) {
// The token has expired, go get a new one.
fetchNewToken(authTokenContext.getVehicleId())
}
return token
}
fun fetchNewToken(vehicleId: String) {
val url =
Uri.Builder()
.scheme("https")
.authority("yourauthserver.example")
.appendPath("token")
.appendQueryParameter("vehicleId", vehicleId)
.build()
.toString()
try {
val reader = InputStreamReader(URL(url).openStream())
reader.use {
val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()
token = obj.get("ServiceToken").getAsString()
expiryTimeMs = obj.get("TokenExpiryMs").getAsLong()
// The expiry time could be an hour from now, but just to try and avoid
// passing expired tokens, we subtract 10 minutes from that time.
expiryTimeMs -= 10 * 60 * 1000
}
} catch (e: IOException) {
// It's OK to throw exceptions here. The StatusListener you passed to
// create the DriverContext class will be notified and passed along the failed
// update warning.
throw RuntimeException("Could not get auth token", e)
}
}
}
Ta konkretna implementacja wykorzystuje wbudowanego klienta HTTP w Javie do pobrania z serwera uwierzytelniania dewelopera. Tokenem jest zapisane do ponownego wykorzystania. Token zostanie pobrany ponownie, jeśli stary token zostanie znaleziony w ciągu 10 minut. po jego upływie.
Implementacja może działać inaczej, np. używać wątku działającego w tle aby odświeżyć tokeny.
Wyjątki w AuthTokenFactory
będą traktowane jako tymczasowe, chyba że wystąpią
kilka razy. Po kilku próbach pakiet Driver SDK
zakłada, że
jest nieodwracalny i przestanie próbować wysyłać aktualizacje.
Raportowanie stanu i błędów za pomocą usługi StatusListener
Pakiet Driver SDK wykonuje działania w
w tle, użyj funkcji StatusListener
, aby otrzymywać powiadomienia, gdy
takich jak błędy, ostrzeżenia czy komunikaty debugowania. Błędy mogą być
przejściowy (np. BACKEND_CONNECTIVITY_ERROR
) lub mogą
powodują trwałe zatrzymanie aktualizacji lokalizacji (np. VEHICLE_NOT_FOUND
,
oznaczający błąd konfiguracji).
Udostępniasz opcjonalną implementację StatusListener
:
Java
class MyStatusListener implements StatusListener {
/** Called when background status is updated, during actions such as location reporting. */
@Override
public void updateStatus(
StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
Kotlin
class MyStatusListener : StatusListener() {
/** Called when background status is updated, during actions such as location reporting. */
override fun updateStatus(statusLevel: StatusLevel, statusCode: StatusCode, statusMsg: String) {
// Status handling stuff goes here.
// StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
// StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
// BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
}
}
Uwagi na temat protokołu SSL/TLS
Wewnętrznie implementacja pakietu Driver SDK używa
Bezpieczna komunikacja z użyciem SSL/TLS
z serwerem Fleet Engine. Starsze wersje Androida (interfejs API w wersji 19 lub
niższy) może wymagać poprawki SecurityProvider
, aby komunikować się z
serwera. Powinno być widoczne to
artykuł
. Artykuł zawiera też
zawiera przykładowy kod służący do instalowania poprawek dostawcy zabezpieczeń.
Włączam aktualizacje lokalizacji
Jeśli masz instancję *VehicleReporter
, włączenie aktualizacji lokalizacji będzie
proste:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Kotlin
val reporter = ...
reporter.enableLocationTracking()
Aktualizacje lokalizacji są regularnie wysyłane, gdy stan pojazdu to
ONLINE
Pamiętaj, że wywołanie numeru reporter.enableLocationTracking()
nie pozwala
automatycznie ustawia stan pojazdu na ONLINE
. Musisz
ustaw stan pojazdu.
Domyślny interwał raportowania wynosi 10 sekund. Interwał raportowania może
zostanie zmieniony przez reporter.setLocationReportingInterval(long, TimeUnit)
.
minimalny obsługiwany interwał aktualizacji to 5 sekund. Częstsze aktualizacje mogą
co skutkuje wolniejszym wysyłaniem żądań i błędami.
Wyłączanie aktualizacji lokalizacji
Po zakończeniu zmiany kierowcy można zatrzymać aktualizacje lokalizacji, a
pojazd oznaczony jako offline przez połączenie
DeliveryVehicleReporter.disableLocationTracking
lub
RidesharingVehicleReporter.disableLocationTracking
Spowoduje to zaplanowanie natychmiastowej aktualizacji ostatniej aktualizacji, z informacją, że pojazd jest offline. Ta aktualizacja nie będzie zawierać danych użytkownika lokalizacji.
Ustawianie stanu pojazdu
Po włączeniu aktualizacji lokalizacji ustawienie stanu pojazdu na ONLINE
spowoduje
udostępnić pojazd w odpowiedzi na SearchVehicles
zapytań; podobnie, oznaczając
pojazd oznaczony jako OFFLINE
oznaczy go jako niedostępny.
Stan pojazdu można ustawić po stronie serwera (patrz Aktualizacja Pojazd), lub bezpośrednio w pakiecie Driver SDK:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);
Kotlin
val reporter = ...
reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)
Gdy aktualizacje lokalizacji są włączone, wywołanie setVehicleState
zostanie wykonane o
przy następnej aktualizacji lokalizacji.
Oznaczenie pojazdu jako ONLINE
przy wyłączonym śledzeniu lokalizacji spowoduje
w: IllegalStateException
. Pojazd może zostać oznaczony jako OFFLINE
, gdy:
śledzenie lokalizacji nie jest jeszcze włączone lub wyłączone. Dzięki temu
natychmiast po aktualizacji. Wywołanie:
RidesharingVehicleReporter.disableLocationTracking()
ustaw stan pojazdu na OFFLINE
.
Pamiętaj, że usługa setVehicleState
wraca natychmiast, a aktualizacje są przeprowadzane
w wątku o aktualizacjach lokalizacji. Podobnie jak w przypadku obsługi błędów przy aktualizacjach lokalizacji, błędów
aktualizacji stanu pojazdu są rozpowszechniane za pomocą opcjonalnie podanej
Pole StatusListener
zostało ustawione w: DriverContext
.