Seyahat ve Sipariş İlerleme Durumu uygulamanızda gelişmiş gezinme ve izleme sağlamak için Sürücü SDK'sını kullanabilirsiniz. Sürücü SDK'sı, İsteğe Bağlı Oyuncaklar ve Teslimatlar Çözüm Filo Motoru için araç konumu ve görev güncellemeleri sağlar.
Sürücü SDK'sı, Fleet Engine hizmetlerinin ve özel hizmetlerinizin aracın konumu ve durumundan haberdar olmasını sağlar. Örneğin, araç ONLINE
veya OFFLINE
olabilir ve yolculuk ilerledikçe aracın konumu değişir.
Minimum sistem gereksinimleri
Mobil cihazın Android 6.0 (API düzeyi 23) veya sonraki bir sürümü çalıştırıyor olması gerekir.
Derleme ve bağımlılık yapılandırması
Sürücü SDK'sının 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ı
Sürücü SDK'sını kullanmak için uygulamanızın minSdkVersion
23 veya sonraki bir sürümü hedeflemesi gerekir.
Sürücü SDK'sı ile oluşturulmuş 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 ayarlamak ve Google Cloud Console'da proje için bir API anahtarı almak için:
Sürücü SDK'sıyla kullanmak için yeni bir Google Cloud Console projesi oluşturun veya mevcut bir projeyi seçin. Yeni proje Google Cloud Console'da görünür olana kadar birkaç dakika bekleyin.
Demo uygulamayı çalıştırmak için 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, ardından Android için Haritalar SDK'sını bulup etkinleştirin.
API'ler ve Hizmetler > Kimlik Bilgileri > Kimlik bilgileri 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ına Google Maven deposundan ulaşabilirsiniz. Bu depo, SDK'nın Proje Nesne Modeli (.pom) dosyalarını ve Java belgelerini içerir. Sürücü SDK'sını uygulamanıza eklemek için:
VERSION_NUMBER
yer tutucusunu Sürücü SDK'sının istenen sürümüyle değiştirerek aşağıdaki bağımlılığı Gradle veya Maven yapılandırmanıza ekleyin.Gradle
build.gradle
cihazınıza aşağıdakileri ekleyin:dependencies { ... implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER' }
Maven
pom.xml
cihazınıza aşağıdakileri 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ü gerektiğinde derleme yapılandırma dosyasında aşağıdaki gibi açıkça tanımlanması gerekir. Belirtilen kod bloğunun atlanması, projenin daima ana sürüm içindeki Navigasyon SDK'sının son sürümünü indirmesini sağlar. Driver SDK'sı ve Navigasyon SDK'sının son sürümlerinin birleşik davranışları, kullanıma sunulmadan önce sıkı testlerden geçmiştir.
Geliştirme ve sürüm ortamlarınızın bağımlılık yapılandırmasını uygun şekilde düzenleyin.
Gradle
build.gradle
cihazınıza aşağıdakileri ekleyin:dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:5.0.0' }
Maven
pom.xml
cihazınıza aşağıdakileri 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 ekleme
Sürücü 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ın daha güvenli bir şekilde referans gösterebilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize girmemelisiniz. Bu dosya, projenizin kök dizininde bulunan local.properties
dosyasında depolanmalıdır. local.properties
dosyası hakkında daha fazla bilgi için Gradle özelliği 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 ve aşağıdaki koduplugins
öğesine 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üzeyi dizininizde
local.properties
dosyasını açın ve aşağıdaki kodu ekleyin.YOUR_API_KEY
öğesini API anahtarınızla değiştirin.MAPS_API_KEY=YOUR_API_KEY
AndroidManifest.xml
dosyanızdacom.google.android.geo.API_KEY
adresine gidipandroid:value
özelliğini aşağıdaki gibi 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 manifestin tamamı 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>
Gerekli ilişkilendirmeleri uygulamanıza dahil edin
Uygulamanızda Sürücü SDK'sını kullanıyorsanız uygulamanızın yasal uyarılar bölümüne atıf metni ve açık kaynak lisansları eklemeniz gerekir. İlişkilendirmeleri bağımsız bir menü öğesi olarak veya Hakkında menü öğesinin parçası olarak eklemeniz önerilir.
Lisans bilgileri, arşivlenmemiş 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 sayfasına bakın.
Bağımlılıklar
Derlemelerinizi optimize etmek için ProGuard'ı kullanıyorsanız ProGuard yapılandırma dosyanıza aşağıdaki satırları 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 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 sayfasını inceleyin.
Sürücü SDK'sını kullanmadan önce, Navigasyon SDK'sını başlatmanız gerekir. SDK'yı başlatmak için:
NavigationApi
öğesinden birNavigator
nesnesi edinin.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
edinin. (*VehicleReporter
değeriNavigationVehicleReporter
tarihinde uzatıldı.)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öndermelidir. Driver SDK, bu isteklerin kimliğini doğrulamak için, arayan tarafından sağlanan AuthTokenFactory
örneğini çağırır.
Konum güncelleme zamanında kimlik doğrulama jetonları oluşturmaktan fabrika sorumludur.
Jetonların tam olarak nasıl oluşturulduğu her geliştiricinin durumuna göre ayrı ayrı belirlenecektir. Ancak, uygulamada muhtemelen:
- HTTPS sunucusundan büyük olasılıkla JSON biçiminde bir kimlik doğrulama jetonu getir
- jetonu ayrıştırıp önbelleğe alın
- süresi dolduğunda 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.
Burada, bir AuthTokenFactory
uygulamasının iskelet uygulaması gösterilmektedir:
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 almak için yerleşik Java HTTP istemcisini kullanır. Jeton yeniden kullanılmak üzere kaydedilir. Eski jeton, geçerlilik süresinin sona ermesinden sonraki 10 dakika içindeyse jeton yeniden getirilir.
Uygulamanız, jetonları yenilemek için arka plan iş parçacığı kullanma gibi bazı işlemleri farklı yapabilir.
AuthTokenFactory
özelliğindeki istisnalar, tekrarlanmadığı sürece geçici olarak değerlendirilir. Birkaç denemeden sonra Sürücü SDK'sı, hatanın kalıcı olduğunu varsayar ve güncelleme göndermeyi bırakır.
StatusListener
ile Durum ve Hata Bildirimi
Sürücü SDK'sı arka planda işlem yaptığından hata, uyarı veya hata ayıklama mesajları gibi belirli etkinlikler gerçekleştiğinde bildirim tetiklemek için StatusListener
düğmesini kullanın. Hatalar doğası gereği geçici olabilir (BACKEND_CONNECTIVITY_ERROR
gibi) veya konum güncellemelerinin kalıcı olarak durdurulmasına neden olabilir (ör. VEHICLE_NOT_FOUND
nedeniyle, yapılandırma hatası verilir).
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 ilgili notlar
Sürücü SDK'sı uygulaması, Fleet Engine sunucusuyla güvenli bir şekilde iletişim kurmak için dahili olarak SSL/TLS kullanır. Android'in eski sürümlerinin (API sürümleri 19 veya önceki sürümleri) sunucuyla iletişim kurabilmesi için bir SecurityProvider
yaması gerekebilir. Android'de SSL ile çalışma hakkında daha fazla bilgi için bu makaleye göz atın. Makalede, güvenlik sağlayıcıya yama uygulamak için kullanılan kod örnekleri de bulunmaktadır.
Konum güncellemelerini etkinleştirme
*VehicleReporter
örneğiniz olduğunda konum güncellemelerini etkinleştirmek oldukça kolaydır:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
Kotlin
val reporter = ...
reporter.enableLocationTracking()
Konum güncellemeleri, aracın durumu ONLINE
olduğunda düzenli olarak gönderilir. reporter.enableLocationTracking()
araması, aracın durumunu otomatik olarak ONLINE
şeklinde ayarlamaz. Araç durumunu açıkça 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. Güncellemelerin daha sık yapılması isteklerin daha yavaş olmasına ve hatalara neden olabilir.
Konum güncellemelerini devre dışı bırakma
Sürücü vardiyası tamamlandığında konum güncellemeleri durdurulabilir ve DeliveryVehicleReporter.disableLocationTracking
veya RidesharingVehicleReporter.disableLocationTracking
numaralı telefonu arayarak araç çevrimdışı olarak işaretlenebilir.
Bu çağrı, aracın çevrimdışı olduğunu belirten son bir güncellemenin hemen teslim edilmek üzere planlanmasına neden olur. Bu güncelleme kullanıcının konumunu içermez.
Aracın durumunu ayarlama
Konum güncellemeleri etkinleştirildiğinde, araç durumunun ONLINE
olarak ayarlanması aracı SearchVehicles
sorguları için kullanılabilir hale getirir. Benzer şekilde, bir araç OFFLINE
olarak işaretlenirse araç kullanılamaz olarak işaretlenir.
Araç durumunu sunucu tarafında (bkz. Araç Güncelleme) veya doğrudan Sürücü SDK'sından ayarlayabilirsiniz:
Java
RidesharingVehicleReporter reporter = ...;
reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);
Kotlin
val reporter = ...
reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)
Konum güncellemeleri etkinleştirildiğinde, bir sonraki konum güncellemesinde setVehicleState
numaralı telefona yapılan bir çağrı yayılır.
Konum izleme etkin değilken bir aracı ONLINE
olarak işaretlemek IllegalStateException
sonucunu verir. Konum izleme henüz etkinleştirilmemişse veya açıkça devre dışı bırakılmamışsa araçlar OFFLINE
olarak işaretlenebilir. Bu şekilde hemen güncelleme yapılır. RidesharingVehicleReporter.disableLocationTracking()
çağrısı yapıldığında aracın durumu OFFLINE
olarak ayarlanır.
setVehicleState
öğesinin hemen geri döndüğünü ve güncellemelerin konum güncelleme iş parçacığında yapıldığını unutmayın. Konum güncellemelerindeki hata işlemeye benzer şekilde, araç durumunu güncelleme hataları da DriverContext
içinde isteğe bağlı olarak sağlanan StatusListener
kümesi kullanılarak yayılır.