Android için Driver SDK'yı kullanmaya başlama

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.

Somut bir örnek olarak Android örnek uygulamalarına veya birleştirilmiş örneklere de bakabilirsiniz.

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:

1. 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.

2. 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.

3. 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:

1. 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>
   

2. 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:

1. Kök düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu buildscript altındaki dependencies öğ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")
       }
   }
   

2. Uygulama düzeyindeki build.gradle dosyanızı açın ve plugins öğ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")
   

3. Android Studio kullanıyorsanız projenizi Gradle ile senkronize edin.

4. 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
   

5. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY adresine gidin ve android: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>

Not: En iyi gezinme deneyimi için hem android.permission.ACCESS_COARSE_LOCATION hem de android.permission.ACCESS_FINE_LOCATION izinlerinin kullanıcı tarafından verilmesi gerekir. Uygulama içinde çalışma zamanında bunların ikisini de istediğinizden emin olun.

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:

1. NavigationApi öğesinden bir Navigator 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)
         [e-mail] = navigator
       }
     },
   )
   

2. 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()
   

3. *DriverApi öğesini başlatmak için DriverContext nesnesini kullanın.

   Java

   RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);
   

   Kotlin

   val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)
   

4. 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.