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

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:

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

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

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

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

  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 aşağıdaki kodu plugins öğesine 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ü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
    
  5. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY adresine gidip android: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:

  1. NavigationApi öğesinden bir Navigator 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
        }
      },
    )
    
  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 edinin. (*VehicleReporter değeri NavigationVehicleReporter 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.