Seyahat ve Sipariş İlerlemesi uygulamanıza gelişmiş navigasyon ve izleme sağlamak için Sürücü SDK'sını kullanabilirsiniz. Sürücü SDK'sı, İsteğe Bağlı Yolculuklar ve Teslimatlar Çözüm Fleet Motoru için araç konumu ve görev güncellemeleri sağlar.
Sürücü SDK'sı, Fleet Engine hizmetlerini ve özel hizmetlerinizi aracın konumu ve durumundan haberdar eder. Örneğin, araç ONLINE
veya OFFLINE
olabilir ve gezi ilerledikçe aracın konumu değişir.
Minimum sistem gereksinimleri
Mobil cihazda Android 6.0 (API düzeyi 23) veya sonraki bir sürüm yüklü olmalıdır.
Derleme ve bağımlılık yapılandırması
Sürücü SDK'sı 4.99 ve sonraki sürümleri Google Maven deposundan kullanılabilir.
Gradle
build.gradle
dosyanıza aşağıdakileri ekleyin:
repositories {
...
google()
}
Maven
pom.xml
dosyanıza aşağıdakileri ekleyin:
<project>
...
<repositories>
<repository>
<id>google-maven-repository</id>
<url>https://maven.google.com</url>
</repository>
</repositories>
...
</project>
Proje Yapılandırması
Driver SDK'sını kullanmak için uygulamanızın minSdkVersion
23 veya sonraki bir sürümü hedeflemesi gerekir.
Driver SDK ile oluşturulan bir uygulamayı çalıştırmak için Android cihazda Google Play Hizmetleri yüklü olmalıdır.
Geliştirme projenizi oluşturun
Geliştirme projenizi oluşturmak ve Google Cloud Console'da projenize ait bir API anahtarı almak için:
Driver SDK ile kullanılacak yeni bir Google Cloud Console projesi oluşturun veya mevcut bir projeyi seçin. Yeni proje Google Cloud Console'da görünene kadar birkaç dakika bekleyin.
Demo uygulamayı çalıştırmak istiyorsanız projenizin Android için Haritalar SDK'sına erişimi olmalıdır. Google Cloud Console'da API'ler ve Hizmetler > Kitaplık'ı seçin ve ardından Android için Haritalar SDK'sını bulup etkinleştirin.
API'ler ve Hizmetler > Kimlik bilgileri > Kimlik bilgisi oluştur > API anahtarı'nı seçerek proje için bir API anahtarı alın. API anahtarı alma hakkında daha fazla bilgi için API anahtarı alma bölümüne bakın.
Sürücü SDK'sını uygulamanıza ekleyin
Sürücü SDK'sı, Google Maven deposundan edinilebilir. Depo, SDK'nın Proje Nesne Modeli (.pom) dosyalarını ve Javadocs'larını içerir. Sürücü SDK'sını uygulamanıza eklemek için:
Aşağıdaki bağımlılığı Gradle veya Maven yapılandırmanıza ekleyerek
VERSION_NUMBER
yer tutucusunu Driver SDK'nın istediğiniz sürümü ile değiştirin.Gradle
build.gradle
cihazınıza şunları ekleyin:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER' }
Maven
pom.xml
cihazınıza şunları ekleyin:<dependencies> ... <dependency> <groupId>com.google.android.libraries.mapsplatform.transportation</groupId> <artifactId>transportation-driver</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
Sürücü SDK'sı, Navigation SDK'ya bağlıdır. Bu bağımlılık, Navigation SDK'nın belirli bir sürümünün gerekli olması durumunda derleme yapılandırma dosyasında aşağıdaki gibi açıkça tanımlanmasını gerektirecek şekilde yapılandırılır. Belirtilen kod bloğunun atlanması, projenin ana sürüm sürümünde her zaman Navigasyon SDK'sının en son sürümünü indirebilmesini sağlar. Driver SDK ve Navigation SDK'nın son sürümlerinin birleşik davranışlarının, yayınlanmadan önce titiz testlerden geçtiğini unutmayın.
Geliştirme ve yayınlama ortamlarınızın bağımlılık yapılandırmasını buna göre düzenleyin.
Gradle
build.gradle
cihazınıza şunları ekleyin:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:5.0.0' }
Maven
pom.xml
cihazınıza şunları ekleyin:<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>5.0.0</version> </dependency> </dependencies>
API anahtarını uygulamanıza ekleyin
Driver SDK'sını uygulamanıza ekledikten sonra API anahtarını uygulamanıza ekleyin. Geliştirme projenizi oluştururken edindiğiniz proje API anahtarını kullanmanız gerekir.
Bu bölümde, uygulamanız tarafından daha güvenli bir şekilde referans verilebilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize kontrol etmemelisiniz. Projenizin kök dizininde bulunan local.properties
dosyasında depolanmalıdır. local.properties
dosyası hakkında daha fazla bilgi için Gradle özellikleri dosyaları bölümüne bakın.
Bu görevi kolaylaştırmak için Android için Secrets Gradle Eklentisi'ni kullanabilirsiniz.
Eklentiyi yüklemek ve API anahtarınızı saklamak için:
Kök düzeyindeki
build.gradle
dosyanızı açın ve aşağıdaki kodubuildscript
altındakidependencies
öğesine ekleyin.Modern
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") } }
Uygulama düzeyindeki
build.gradle
dosyanızı açın veplugins
öğesine aşağıdaki kodu ekleyin.Modern
id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
Kotlin
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
Android Studio kullanıyorsanız projenizi Gradle ile senkronize edin.
Proje düzeyindeki dizinde
local.properties
dosyasını açın ve aşağıdaki kodu ekleyin.YOUR_API_KEY
kısmını API anahtarınızla değiştirin.MAPS_API_KEY=YOUR_API_KEY
AndroidManifest.xml
dosyanızdacom.google.android.geo.API_KEY
adresine gidin veandroid:value
özelliğini aşağıdaki şekilde güncelleyin:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
Aşağıdaki örnekte, örnek bir uygulama için eksiksiz bir manifest gösterilmektedir:
<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>
Uygulamanıza gerekli ilişkilendirmeleri dahil edin
Uygulamanızda Driver SDK'sını kullanıyorsanız uygulamanızın yasal uyarılar bölümünün bir parçası olarak atıf metni ve açık kaynak lisansları eklemeniz gerekir. İlişkilendirmeleri bağımsız bir menü öğesi veya bir Hakkında menü öğesinin parçası olarak eklemek en iyisidir.
Lisans bilgileri, arşivden çıkarılmış AAR dosyasındaki "third_party_LICENSEs.txt" dosyasında bulunabilir.
Açık kaynak bildirimlerini nasıl ekleyeceğinizi öğrenmek için https://developers.google.com/android/guides/opensource adresine bakın.
Bağımlılıklar
Derlemelerinizi optimize etmek için ProGuard kullanıyorsanız aşağıdaki satırları ProGuard yapılandırma dosyanıza eklemeniz gerekebilir:
-dontwarn com.google.**
-dontwarn okio.**
Desteklenen minimum API düzeyi 23'tür.
SDK'yı Başlatma
DriverContext
nesnesini başlatmak için bir sağlayıcı kimliği (genellikle Google Cloud proje kimliği) gerekir. Google Cloud projesini ayarlama hakkında daha fazla bilgi için Kimlik Doğrulama ve Yetkilendirme bölümüne bakın.
Driver SDK'sını kullanmadan önce Navigasyon SDK'sını başlatmanız gerekir. SDK'yı başlatmak için:
NavigationApi
öğesinden birNavigator
nesnesi alın.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 } }, )
Zorunlu alanları doldurarak bir
DriverContext
nesnesi oluşturun.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()
*DriverApi
öğesini başlatmak içinDriverContext
nesnesini kullanın.Java
RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
Kotlin
val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
API nesnesinden
RidesharingVehicleReporter
öğesini alın. (*VehicleReporter
,NavigationVehicleReporter
süresini uzatır.)Java
RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();
Kotlin
val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()
AuthTokenFactory
üzerinde kimlik doğrulanıyor
Sürücü SDK'sı konum güncellemeleri oluşturduğunda bu güncellemeleri Fleet Engine sunucusuna göndermesi gerekir. Sürücü SDK, bu isteklerin kimliğini doğrulamak için çağrı tarafından sağlanan AuthTokenFactory
örneğine çağrı yapar.
Fabrika, konum güncelleme zamanında kimlik doğrulama jetonları oluşturmaktan sorumludur.
Jetonların tam olarak nasıl oluşturulduğu her geliştiricinin kendi durumuna göre değişir. Ancak, uygulama işlemi için muhtemelen:
- bir HTTPS sunucusundan JSON biçiminde kimlik doğrulama jetonu getirme
- jetonu ayrıştırıp önbelleğe alın
- Süresi dolduğunda jetonu yenile
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.
Aşağıda AuthTokenFactory
iskelet uygulaması verilmiştir:
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)
}
}
}
Bu özel uygulama, geliştiricinin kimlik doğrulama sunucusundan JSON biçiminde bir jeton getirmek için yerleşik Java HTTP istemcisini kullanır. Jeton yeniden kullanılmak üzere kaydedilir. Eski jetonun geçerlilik bitiş tarihinden önceki 10 dakika içindeyse jeton tekrar getirilir.
Uygulamanız, jetonları yenilemek için arka plan ileti dizisi kullanmak gibi işleri farklı şekilde yapabilir.
AuthTokenFactory
ürünündeki istisnalar, tekrar tekrar yapılmadığı sürece geçici olarak değerlendirilir. Birkaç denemeden sonra Driver SDK, hatanın kalıcı olduğunu varsayar ve güncelleme göndermeyi durdurur.
StatusListener
ile Durum ve Hata Bildirimi
Driver SDK arka planda işlemler gerçekleştirdiğinden; hata, uyarı veya hata ayıklama mesajı gibi belirli olaylar gerçekleştiğinde bildirimleri tetiklemek için StatusListener
bileşenini kullanın. Hatalar geçici olabilir (BACKEND_CONNECTIVITY_ERROR
gibi) veya konum güncellemelerinin kalıcı olarak durdurulmasına neden olabilir (VEHICLE_NOT_FOUND
gibi bir yapılandırma hatasına işaret eder).
Aşağıdaki gibi isteğe bağlı bir StatusListener
uygulaması sağlarsınız:
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.
}
}
SSL/TLS ile İlgili Notlar
Sürücü SDK'sı uygulaması, dahili olarak Fleet Engine sunucusuyla güvenli iletişim kurmak için SSL/TLS kullanır. Android'in eski sürümleri (API 19 veya önceki sürümler), sunucuyla iletişim kurabilmek için SecurityProvider
yaması gerektirebilir. Android'de SSL ile çalışma hakkında daha fazla bilgi için bu makaleyi inceleyin. Makalede, güvenlik sağlayıcıya yama uygulamak için kullanabileceğiniz kod örnekleri de bulunmaktadır.
Konum güncellemelerini etkinleştirme
Bir *VehicleReporter
örneği oluşturduktan sonra, konum güncellemelerini etkinleştirmek oldukça kolaydır:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Kotlin
val reporter = ...
reporter.enableLocationTracking()
Konum güncellemeleri, araç durumu ONLINE
olduğunda düzenli aralıklarla gönderilir. reporter.enableLocationTracking()
arandığında araç durumu otomatik olarak ONLINE
olarak ayarlanmaz. Araç durumunu açık bir şekilde ayarlamanız gerekir.
Varsayılan olarak raporlama aralığı 10 saniyedir. Raporlama aralığı reporter.setLocationReportingInterval(long, TimeUnit)
ile değiştirilebilir. Desteklenen minimum güncelleme aralığı 5 saniyedir. Daha sık güncelleme yapmak, daha yavaş isteklere ve hatalara neden olabilir.
Konum güncellemeleri devre dışı bırakılıyor
Sürücünün vardiyası bittiğinde, konum güncellemeleri durdurulabilir ve
DeliveryVehicleReporter.disableLocationTracking
veya
RidesharingVehicleReporter.disableLocationTracking
aranarak araç çevrimdışı olarak işaretlenebilir.
Bu çağrı, hemen teslim edilmek üzere son bir güncellemenin planlanmasına neden olur. Bu, aracın çevrimdışı olduğunu belirtir. Bu güncelleme, kullanıcının konumunu içermez.
Araç durumunu ayarlama
Konum güncellemeleri etkinleştirildiğinde araç durumunun ONLINE
olarak ayarlanması, aracı SearchVehicles
sorgularında kullanılabilir hale getirir. Benzer şekilde, aracı OFFLINE
olarak işaretlediğinizde de araç kullanılamaz olarak işaretlenir.
Araç durumunu sunucu tarafında (Araç Güncelleme bölümüne bakın) veya doğrudan Driver SDK'da ayarlama seçeneğiniz vardır:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);
Kotlin
val reporter = ...
reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)
Konum güncellemeleri etkinleştirildiğinde setVehicleState
için yapılan bir çağrı bir sonraki konum güncellemesinde uygulanır.
Konum izleme etkin değilken bir aracı ONLINE
olarak işaretlemek IllegalStateException
ile sonuçlanır. Konum izleme henüz etkinleştirilmediğinde veya açıkça devre dışı bırakıldığında bir araç OFFLINE
olarak işaretlenebilir. Bu işlem anında
güncelleme yapılır. RidesharingVehicleReporter.disableLocationTracking()
çağrısı yapıldığında araç durumu OFFLINE
olarak ayarlanır.
setVehicleState
öğesinin hemen geri döndüğünü ve güncellemelerin konum güncelleme ileti dizisinde yapıldığını unutmayın. Konum güncellemelerindeki hataların işlenmesine benzer şekilde, araç durumu güncellenirken DriverContext
içindeki isteğe bağlı olarak sağlanan StatusListener
ayarı kullanılarak yayılır.