On-demand Rides and Deliveries Solution is currently available only to select partners.

Diese Seite wurde von der Cloud Translation API übersetzt.

Erste Schritte mit dem Driver SDK für Android

Mit dem Driver SDK können Sie die Navigation und die Nachverfolgung Ihrer App für Fahrten und Bestellfortschritte verbessern. Das Driver SDK stellt Aktualisierungen des Fahrzeugstandorts und der Aufgaben für die On-Demand-Flotten-Engine der Lösung „Rides and Deliveries“ bereit.

Das Driver SDK informiert die Fleet Engine-Dienste und Ihre benutzerdefinierten Dienste über den Standort und den Status des Fahrzeugs. Das Fahrzeug kann beispielsweise ONLINE oder OFFLINE sein und der Standort des Fahrzeugs ändert sich im Laufe der Fahrt.

Mindestsystemanforderungen

Auf dem Mobilgerät muss Android 5.0 (API-Level 21) oder höher installiert sein.

Maven-Konfiguration

Treiber-SDK-Versionen 4.99 und höher sind über das Google Maven-Repository verfügbar.

Gradle

Füge deiner Datei build.gradle Folgendes hinzu:

repositories {
    ...
    google()
}

Maven

Füge deiner Datei pom.xml Folgendes hinzu:

<project>
  ...
  <repositories>
    <repository>
      <id>google-maven-repository</id>
      <url>https://maven.google.com</url>
    </repository>
  </repositories>
  ...
</project>

Projektkonfiguration

Wenn Sie das Treiber SDK verwenden möchten, muss Ihre App auf minSdkVersion 21 oder höher ausgerichtet sein.

Zum Ausführen einer App, die mit dem Treiber SDK erstellt wurde, müssen auf dem Android-Gerät Google Play-Dienste installiert sein.

Entwicklungsprojekt einrichten

So richten Sie in der Google Cloud Console Ihr Entwicklungsprojekt ein und rufen einen API-Schlüssel für das Projekt ab:

Erstellen Sie ein neues Google Cloud Console-Projekt oder wählen Sie ein vorhandenes Projekt zur Verwendung mit dem Driver SDK aus. Warten Sie einige Minuten, bis das neue Projekt in der Google Cloud Console angezeigt wird.
Zum Ausführen der Demo-App muss Ihr Projekt Zugriff auf das Maps SDK for Android haben. Wählen Sie in der Google Cloud Console APIs und Dienste > Bibliothek aus, suchen Sie nach dem Maps SDK for Android und aktivieren Sie es.
Fordern Sie unter APIs und Dienste > Anmeldedaten > Anmeldedaten erstellen > API-Schlüssel einen API-Schlüssel für das Projekt an. Weitere Informationen zum Abrufen eines API-Schlüssels findest du unter API-Schlüssel abrufen.

Treiber-SDK zur App hinzufügen

Das Treiber-SDK ist über ein privates Maven-Repository verfügbar. Das Repository enthält die Projektobjektmodelldateien (.pom) des SDK und Javadocs. So fügen Sie Ihrer App das Treiber-SDK hinzu:

Fügen Sie Ihrer Gradle- oder Maven-Konfiguration die folgende Abhängigkeit hinzu und ersetzen Sie den Platzhalter VERSION_NUMBER durch die gewünschte Version des Driver SDK.

Gradle

Fügen Sie zum build.gradle Folgendes hinzu:

dependencies {
  ...
  implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-driver:VERSION_NUMBER'
}

Maven

Fügen Sie zum pom.xml Folgendes hinzu:

<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.mapsplatform.transportation</groupId>
    <artifactId>transportation-driver</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

API-Schlüssel in die App einfügen

Fügen Sie der App den API-Schlüssel hinzu, nachdem Sie Ihrer App das Treiber-SDK hinzugefügt haben. Dazu müssen Sie den Projekt-API-Schlüssel verwenden, den Sie bei der Einrichtung Ihres Entwicklungsprojekts erhalten haben.

In diesem Abschnitt wird beschrieben, wie Sie Ihren API-Schlüssel speichern, damit er von Ihrer App sicherer referenziert werden kann. Er sollte nicht in Ihr Versionsverwaltungssystem eingecheckt werden. Sie sollte in der Datei local.properties gespeichert werden, die sich im Stammverzeichnis Ihres Projekts befindet. Weitere Informationen zur Datei local.properties finden Sie unter Gradle properties files.

Sie können das Secrets Gradle Plugin for Android verwenden, um diese Aufgabe zu optimieren.

So installieren Sie das Plug-in und speichern Ihren API-Schlüssel:

Öffnen Sie die Datei build.gradle auf Stammebene und fügen Sie den folgenden Code in das Element dependencies unter buildscript ein.

Groovy

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")
    }
}

Öffnen Sie die Datei build.gradle auf App-Ebene und fügen Sie dem Element plugins den folgenden Code hinzu.

Groovy

id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'

Kotlin

id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")

Wenn Sie Android Studio verwenden, synchronisieren Sie Ihr Projekt mit Gradle.
Öffnen Sie local.properties in Ihrem Verzeichnis auf Projektebene und fügen Sie den folgenden Code hinzu. ersetzen Sie dabei YOUR_API_KEY durch Ihren eigenen API-Schlüssel:
```
MAPS_API_KEY=YOUR_API_KEY
```
Gehen Sie in der Datei AndroidManifest.xml zu com.google.android.geo.API_KEY und aktualisieren Sie das Attribut android:value so:
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```

Das folgende Beispiel zeigt ein vollständiges Manifest für eine Beispiel-App:

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

Füge deiner App die erforderlichen Quellenangaben hinzu

Wenn Sie das Treiber-SDK in Ihrer App verwenden, müssen Sie im Abschnitt mit den rechtlichen Hinweisen Ihrer App Quellenangaben und Open-Source-Lizenzen hinzufügen. Es empfiehlt sich, die Zuordnungen als eigenständiges Menüelement oder als Teil des Menüpunkts Info anzugeben.

Den erforderlichen Quellenangabentext und die Open-Source-Lizenzen finden Sie in der ZIP-Datei mit dem Driver SDK:

NOTICE.txt
LICENSES.txt

Abhängigkeiten

Wenn Sie Ihre Builds mit ProGuard optimieren, müssen Sie Ihrer ProGuard-Konfigurationsdatei möglicherweise die folgenden Zeilen hinzufügen:

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

Das unterstützte Mindest-API-Level ist 21.

SDK initialisieren

Zum Initialisieren des DriverContext-Objekts ist eine Anbieter-ID (in der Regel die Google Cloud-Projekt-ID) erforderlich. Weitere Informationen zum Einrichten des Google Cloud-Projekts finden Sie unter Authentifizierung und Autorisierung.

Bevor Sie das Driver SDK verwenden können, müssen Sie zuerst das Navigation SDK initialisieren. So initialisieren Sie das SDK:

Rufen Sie ein Navigator-Objekt aus dem NavigationApi ab.

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
    }
  },
)

Erstellen Sie ein DriverContext-Objekt und füllen Sie die Pflichtfelder aus.

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

Verwenden Sie das Objekt DriverContext, um *DriverApi zu initialisieren.

Java

RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);

Kotlin

val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)

Rufen Sie den RidesharingVehicleReporter aus dem API-Objekt ab. (*VehicleReporter erweitert NavigationVehicleReporter.)

Java

RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();

Kotlin

val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()

Authentifizierung bei `AuthTokenFactory`

Wenn das Driver SDK Standortaktualisierungen generiert, müssen diese an den Fleet Engine-Server gesendet werden. Zum Authentifizieren dieser Anfragen ruft das Driver SDK eine vom Aufrufer bereitgestellte Instanz von AuthTokenFactory auf. Die Factory ist für das Generieren von Authentifizierungstokens zum Zeitpunkt der Standortaktualisierung verantwortlich.

Wie genau Tokens generiert werden, hängt von der Situation des jeweiligen Entwicklers ab. Für die Implementierung ist wahrscheinlich jedoch Folgendes erforderlich:

ein Authentifizierungstoken von einem HTTPS-Server abrufen, möglicherweise im JSON-Format
Token parsen und im Cache speichern
Token aktualisieren, wenn es abläuft

Weitere Informationen zu den vom Fleet Engine-Server erwarteten Tokens finden Sie unter JSON Web Token (JWT) für die Autorisierung erstellen.

Hier ist eine grundlegende Implementierung eines AuthTokenFactory:

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)
    }
  }
}

Diese spezielle Implementierung verwendet den integrierten Java-HTTP-Client, um ein Token im JSON-Format vom Authentifizierungsserver des Entwicklers abzurufen. Das Token wird zur Wiederverwendung gespeichert. Das Token wird noch einmal abgerufen, wenn sich das alte Token innerhalb von 10 Minuten nach seiner Ablaufzeit befindet.

Ihre Implementierung kann andere Schritte ausführen, z. B. die Verwendung eines Hintergrundthreads zum Aktualisieren von Tokens.

Ausnahmen in AuthTokenFactory werden als vorübergehend behandelt, es sei denn, sie treten wiederholt auf. Nach mehreren Versuchen geht das Driver SDK davon aus, dass der Fehler dauerhaft ist, und sendet keine Updates mehr.

Status- und Error Reporting mit `StatusListener`

Da das Driver SDK Aktionen im Hintergrund ausführt, verwenden Sie StatusListener, um bei bestimmten Ereignissen Benachrichtigungen auszulösen, z. B. bei Fehlern, Warnungen oder Meldungen zur Fehlerbehebung. Fehler können vorübergehend sein (z. B. BACKEND_CONNECTIVITY_ERROR) oder dazu führen, dass Standortaktualisierungen dauerhaft gestoppt werden (z. B. VEHICLE_NOT_FOUND, die einen Konfigurationsfehler anzeigen).

Du stellst eine optionale StatusListener-Implementierung wie die folgende bereit:

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

Hinweise zu SSL/TLS

Intern verwendet die Treiber-SDK-Implementierung SSL/TLS, um sicher mit dem Fleet Engine-Server zu kommunizieren. Ältere Android-Versionen (API-Versionen 19 oder niedriger) erfordern möglicherweise einen SecurityProvider-Patch, um mit dem Server kommunizieren zu können. Weitere Informationen zur Arbeit mit SSL in Android finden Sie in diesem Artikel. Der Artikel enthält auch Codebeispiele zum Patchen des Sicherheitsanbieters.

Standortupdates aktivieren

Sobald Sie eine *VehicleReporter-Instanz haben, können Sie Standortaktualisierungen ganz einfach aktivieren:

Java

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Kotlin

val reporter = ...

reporter.enableLocationTracking()

Standortaktualisierungen werden in regelmäßigen Abständen gesendet, wenn der Fahrzeugstatus ONLINE ist. Durch das Aufrufen von reporter.enableLocationTracking() wird der Fahrzeugstatus nicht automatisch auf ONLINE gesetzt. Sie müssen den Fahrzeugstatus explizit festlegen.

Standardmäßig beträgt das Berichtsintervall 10 Sekunden. Das Berichtsintervall kann mit reporter.setLocationReportingInterval(long, TimeUnit) geändert werden. Das unterstützte Mindestintervall beträgt 5 Sekunden. Häufigere Aktualisierungen können zu langsameren Anfragen und Fehlern führen.

Standortupdates deaktivieren

Wenn die Schicht des Fahrers beendet ist, können Standortaktualisierungen angehalten und das Fahrzeug als offline markiert werden, indem DeliveryVehicleReporter.disableLocationTracking oder RidesharingVehicleReporter.disableLocationTracking aufgerufen wird.

Durch diesen Aufruf wird eine letzte Aktualisierung für die sofortige Lieferung geplant. Das bedeutet, dass das Fahrzeug offline ist. Bei diesem Update wird der Standort des Nutzers nicht angegeben.

Fahrzeugstatus festlegen

Wenn Standortaktualisierungen aktiviert sind und der Fahrzeugstatus auf ONLINE gesetzt wird, wird das Fahrzeug für SearchVehicles-Abfragen verfügbar gemacht. Wenn ein Fahrzeug mit OFFLINE gekennzeichnet wird, wird es als nicht verfügbar markiert.

Sie können den Fahrzeugstatus serverseitig (siehe Fahrzeug aktualisieren) oder direkt im Driver SDK festlegen:

Java

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);

Kotlin

val reporter = ...

reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)

Wenn Standortaktualisierungen aktiviert sind, wird ein Aufruf von setVehicleState beim nächsten Standortupdate weitergeleitet.

Wenn ein Fahrzeug als ONLINE markiert wird, wenn die Standortermittlung nicht aktiviert ist, wird ein IllegalStateException ausgelöst. Ein Fahrzeug kann als OFFLINE gekennzeichnet werden, wenn die Standortermittlung noch nicht aktiviert oder explizit deaktiviert ist. Dies führt zu einer sofortigen Aktualisierung. Durch einen Aufruf von RidesharingVehicleReporter.disableLocationTracking() wird der Fahrzeugstatus auf OFFLINE gesetzt.

setVehicleState wird sofort zurückgegeben und Aktualisierungen werden im Thread des Standortaktualisierungs-Threads durchgeführt. Ähnlich wie bei der Fehlerbehandlung bei Standortaktualisierungen werden Fehler bei der Aktualisierung des Fahrzeugstatus über das optional bereitgestellte StatusListener weitergegeben, das in DriverContext festgelegt ist.

Erste Schritte mit dem Driver SDK für Android

Mindestsystemanforderungen

Maven-Konfiguration

Gradle

Maven

Projektkonfiguration

Entwicklungsprojekt einrichten

Treiber-SDK zur App hinzufügen

Gradle

Maven

API-Schlüssel in die App einfügen

Groovy

Kotlin

Groovy

Kotlin

Füge deiner App die erforderlichen Quellenangaben hinzu

Abhängigkeiten

SDK initialisieren

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Authentifizierung bei AuthTokenFactory

Java

Kotlin

Status- und Error Reporting mit StatusListener

Java

Kotlin

Hinweise zu SSL/TLS

Standortupdates aktivieren

Java

Kotlin

Standortupdates deaktivieren

Fahrzeugstatus festlegen

Java

Kotlin

Authentifizierung bei `AuthTokenFactory`

Status- und Error Reporting mit `StatusListener`