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

Gelişmiş gezinme ve izleme özellikleri sunmak için Driver SDK'sını kullanabilirsiniz. ve Sipariş İlerlemesi başvurunuza ekleyin. Sürücü SDK'sı, İsteğe Bağlı Yolculuklar ve Teslimatlar Çözümü Filo Motoru'nda araç konumu ve görev güncellemeleri.

Sürücü SDK'sı, Fleet Engine hizmetlerini ve özel hizmetlerinizi haberdar eder konumunu ve durumunu görebilirsiniz. Örneğin, araç ONLINE olabilir veya OFFLINE ve gezi ilerledikçe aracın konumu değişir.

Android örnek uygulamalarına da bakabilirsiniz veya kombine örnekler somut bir örnek verelim.

Minimum sistem gereksinimleri

Mobil cihaz Android 6.0 sürümünü çalıştırmalıdır (API düzeyi 23) veya üzeri.

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ı

Sürücü SDK'sını kullanmak için uygulamanızın şunları hedeflemesi gerekir: minSdkVersion 23 veya sonraki sürümler.

Sürücü SDK'sı ile oluşturulmuş bir uygulamayı çalıştırmak için Android cihazda şunlar olmalıdır: Google Play Hizmetleri yüklendi.

Geliştirme projenizi oluşturun

Geliştirme projenizi oluşturmak ve API anahtarı almak için Google Cloud Console'da projeniz için:

1. Kullanmak için yeni bir Google Cloud Console projesi oluşturun veya mevcut bir projeyi seçin Sürücü SDK'sı ile. Birkaç dakika bekleyin. Google Cloud Console'da görünür olduğundan emin olun.

2. Demo uygulamayı çalıştırmak için projenizin Haritalar SDK'sına erişimi olmalıdır Android için. Google Cloud Console'da aşağıdakilerden birini seçin: API'ler ve Hizmetler > Kitaplık'ı tıklayın, ardından şunun için Haritalar SDK'sını arayın: Android

3. Şu seçeneği belirleyerek proje için bir API anahtarı alın: API'ler ve Hizmetler > Kimlik Bilgileri > Kimlik bilgileri oluştur > API anahtarı. API anahtarı alma hakkında daha fazla bilgi için bkz. API anahtarı alın.

Sürücü SDK'sını uygulamanıza ekleyin

Sürücü SDK'sı, Google Maven deposundan edinilebilir. İlgili içeriği oluşturmak için kullanılan deposu, SDK'nın Proje Nesne Modeli (.pom) dosyalarını ve Javadocs'u 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 ekleyin. Sürücü SDK'sının istenen sürümü için VERSION_NUMBER yer tutucusu.

   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ı, Navigasyon SDK'sına bağlıdır. Bu bağımlılık Bu şekilde, belirli bir Gezinme SDK'sı sürümü gerekiyorsa o sürümün aşağıdaki gibi derleme yapılandırma dosyasında açıkça tanımlanır, belirtilen kod bloğunun atlanması, projenin her zaman Navigasyon SDK'sının ana sürüm sürümüne sahip olması gerekir. Driver SDK'nın son sürümlerinin ve bu sürümlerin birlikte çalışan Gezinme SDK'sı, yayınlanmadan önce titiz testlerden geçmiştir.

   Geliştirme ve sürümünüzün bağımlılık yapılandırmasını düzenleyin uygun şekilde düzenlemenizi sağlar.

   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. Siz geliştirme projenizi oluşturun.

Bu bölümde, daha güvenli olması için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. veya üçüncü taraf uygulamadır. Sürümünüzde API anahtarınızı kontrol etmemelisiniz kontrol sistemi. Bu veriler, local.properties dosyasında depolanmalıdır. klasörünün herhangi bir bölümünde bulunur. Daha fazla bilgi için local.properties dosyası için bkz. Gradle özellikleri dosyaları.

Bu görevi kolaylaştırmak için Android için Secrets Gradle Plugin.

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ında dependencies öğesi.

   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 aşağıdaki kodu plugins öğesi.

   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 kullanabilirsiniz. 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 şu ş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 ve android.permission.ACCESS_FINE_LOCATION izninin belirtir. Uygulama içinde çalışma zamanında bunların ikisini de istediğinizden emin olun.

Uygulamanıza gerekli ilişkilendirmeleri dahil edin

Uygulamanızda Sürücü SDK'sını kullanıyorsanız uygulamanızın yasal uyarılarının bir parçası olarak atıf metni ve açık kaynak lisansları bölümüne bakın. İlişkilendirmeleri bağımsız bir menü öğesi veya her zaman bir Hakkında menü öğesinin bir bölümüdür.

Lisans bilgileri "third_party_LICENSEs.txt" dosyasında bulunabilir şurada dosyala: arşivden çıkarılan AAR dosyasına dokunun.

https://developers.google.com/android/guides/opensource konusunda daha fazla bilgi edinin.

Bağımlılıklar

ProGuard kullanıyorsanız derlemelerinizi optimize etmek için aşağıdaki satırları ProGuard'a eklemeniz gerekebilir: yapılandırma dosyası:

-dontwarn com.google.**
-dontwarn okio.**

Desteklenen minimum API düzeyi 23'tür.

SDK'yı Başlatma

Şu işlemleri gerçekleştirmek için bir sağlayıcı kimliği (genellikle Google Cloud proje kimliği) gereklidir: DriverContext nesnesini başlatın. Chrome Tarayıcı'yı kurma hakkında daha fazla Google Cloud projesi için bkz. Authentication and Authorization (Kimlik Doğrulama ve Yetkilendirme).

Sürücü SDK'sını kullanmadan önce ilk kullanıma hazırlamanız gerekir gezinme SDK'sı. 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 emin olmaktır. Bu isteklerin kimliğini doğrulamak için Sürücü SDK'sı, arayan tarafından sağlanan bir kullanıcıya çağrı yapar AuthTokenFactory örneği. Fabrika, konumda kimlik doğrulama jetonları oluşturmaktan sorumludur güncelleme zamanı.

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 sunucusunun beklediği jetonların ayrıntıları için bkz. Yetkilendirme için JSON Web Token (JWT) oluşturma.

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, bir web sitesini jetonunu, geliştiricinin kimlik doğrulama sunucusundan JSON biçiminde kaydetmesini isteyin. Jeton yeniden kullanılmak üzere kaydedildi. Eski jeton 10 dakika içindeyse jeton yeniden getirilir sona ereceğini unutmayın.

Uygulamanız, arka plan ileti dizisi kullanmak gibi bazı işlemleri farklı yapabilir tıklayın.

AuthTokenFactory politikasındaki istisnalar, gerçekleşmedikleri sürece geçici olarak değerlendirilecek tekrar tekrar. Bir dizi denemeden sonra Sürücü SDK'sı sayfanın hatası kalıcıdır ve artık güncelleme göndermeyi durduracaktır.

StatusListener ile Durum ve Hata Bildirimi

Sürücü SDK'sı bazı durumlarda bildirimleri tetiklemek için StatusListener hata, uyarı veya hata ayıklama mesajı gibi çeşitli etkinliklerin meydana gelmesidir. Hatalar şunlar olabilir: geçici (BACKEND_CONNECTIVITY_ERROR gibi) veya konum güncellemelerinin kalıcı olarak durdurulmasına neden olur (ör. VEHICLE_NOT_FOUND, Bu bir yapılandırma hatası anlamına gelir).

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, Güvenli iletişim için SSL/TLS farklı bir kod var. Android'in eski sürümleri (API sürümleri 19 veya daha düşük) ile iletişim kurulabilmesi için bir SecurityProvider yaması gerekebilir sunucu. Şunu görmeniz gerekir: makale makalesini okuyabilirsiniz. Makalede ayrıca güvenlik sağlayıcısına yama uygulamak için kullanılan kod örneklerini içerir.

Konum güncellemelerini etkinleştirme

Bir *VehicleReporter örneğiniz olduğunda konum güncellemelerinin etkinleştirilmesi basittir:

Java

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Kotlin

val reporter = ...

reporter.enableLocationTracking()

Araç durumu şu olduğunda düzenli aralıklarla konum güncellemeleri gönderilir: ONLINE reporter.enableLocationTracking() adlı kişiye çağrı yapmanın araç durumunu otomatik olarak ONLINE değerine ayarladı. Şunu yapmalısınız: araç durumunu açık bir şekilde ayarlayabilirsiniz.

Varsayılan olarak raporlama aralığı 10 saniyedir. Raporlama aralığı reporter.setLocationReportingInterval(long, TimeUnit) ile değiştirilir. İlgili içeriği oluşturmak için kullanılan desteklenen minimum güncelleme aralığı 5 saniyedir. Güncelleme sıklığı arttıkça daha yavaş istek ve hatalara neden olur.

Konum güncellemeleri devre dışı bırakılıyor

Sürücünün vardiyası bittiğinde konum güncellemeleri durdurulabilir ve araç sesli arama yapılarak çevrimdışı işaretlendi DeliveryVehicleReporter.disableLocationTracking veya RidesharingVehicleReporter.disableLocationTracking.

Bu çağrı, hemen teslim edilmek üzere son bir güncellemenin planlanmasına neden olacak. Bu, aracın çevrimdışı olduğunu gösterir. Bu güncelleme, kullanıcıya ait konum.

Araç durumunu ayarlama

Konum güncellemeleri etkinleştirildiğinde araç durumunu ONLINE olarak ayarlamak aracı SearchVehicles sorgu için kullanılabilir hale getirin; benzer şekilde OFFLINE olarak işaretlenir. Araç, kullanılamaz olarak işaretlenir.

Araç durumunu sunucu tarafında ayarlama seçeneğiniz vardır (bkz. Güncelleme Araç), veya doğrudan Driver SDK'sında:

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 çağrısına şu saatte gönderilecek: emin olun.

Konum izleme etkin değilken bir aracı ONLINE olarak işaretlerseniz IllegalStateException içinde Bir araç aşağıdaki durumlarda OFFLINE olarak işaretlenebilir: Konum izleme henüz etkinleştirilmedi veya açıkça devre dışı bırakıldı. Bu, hemen güncellenecek. Bir RidesharingVehicleReporter.disableLocationTracking() şunu yapacak: araç durumunu OFFLINE olarak ayarla.

setVehicleState web sitesinin hemen geri döneceğini ve güncellemelerin şurada yapıldığını unutmayın: konum güncelleme ileti dizisi. Konum güncellemelerindeki hataların işlenmesine benzer şekilde, hatalar Araç durumunun güncellenmesi, isteğe bağlı olarak sağlanan StatusListener, DriverContext içinde ayarlandı.