Guida introduttiva all'SDK di Drive per Android

Requisiti minimi di sistema

Sul dispositivo mobile deve essere installato Android 6.0 (livello API 23) o versioni successive.

Configurazione e configurazione delle dipendenze

Le versioni dell'SDK Driver 4.99 e successive sono disponibili nel Repository Maven di Google.

Gradle

Aggiungi quanto segue al tuo file build.gradle:

repositories {
    ...
    google()
}

Maven

Aggiungi quanto segue al tuo file pom.xml:

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

Configurazione progetto

Per utilizzare l'SDK Driver, la tua app deve avere come target minSdkVersion 23 o versioni successive. Per ulteriori informazioni, consulta le Note di rilascio.

Per eseguire un'app creata con l'SDK Driver, sul dispositivo Android deve essere installato Google Play Services.

Configura il progetto di sviluppo

Per configurare il progetto di sviluppo e ottenere una chiave API per il progetto nella console Google Cloud:

  1. Crea un nuovo progetto nella console Google Cloud o selezionane uno esistente per utilizzarlo con l'SDK di Driver. Attendi qualche minuto finché il nuovo progetto non è visibile nella console Google Cloud.

  2. Per eseguire l'app demo, il tuo progetto deve avere accesso a Maps SDK for Android. Nella console Google Cloud, seleziona API e servizi > Libreria, quindi cerca e abilita Maps SDK for Android.

  3. Ottieni una chiave API per il progetto selezionando API e servizi > Credenziali > Crea credenziali > Chiave API. Per saperne di più su come ottenere una chiave API, consulta Ottenere una chiave API.

Aggiungi l'SDK Driver alla tua app

L'SDK Driver è disponibile nel Repository Maven di Google. Il repository include i file Project Object Model (.pom) e Javadocs dell'SDK. Per aggiungere l'SDK Driver alla tua app:

  1. Aggiungi la seguente dipendenza alla configurazione Gradle o Maven, sostituendo il segnaposto VERSION_NUMBER con la versione selezionata dell'SDK Driver.

    Gradle

    Aggiungi il seguente codice a build.gradle:

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

    Maven

    Aggiungi il seguente codice a pom.xml:

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

  2. L'SDK Driver dipende dall'SDK di navigazione, questa dipendenza è configurata in modo tale che, se è necessaria una versione specifica dell'SDK di navigazione, questa deve essere definita esplicitamente nel file di configurazione della build come segue. Se il blocco di codice indicato viene omesso, il progetto potrà scaricare sempre la versione più recente dell'SDK di navigazione all'interno della versione di release principale. Tieni presente che i comportamenti combinati delle versioni più recenti di Driver SDK e Navigator SDK sono stati sottoposti a test rigorosi prima delle loro release.

    Organizza la configurazione delle dipendenze nei tuoi ambienti di sviluppo e rilascio di conseguenza.

    Gradle

    Aggiungi il seguente codice a build.gradle:

    dependencies {
  ...
  implementation 'com.google.android.libraries.navigation:navigation:5.0.0'
}

    Maven

    Aggiungi il seguente codice a pom.xml:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>5.0.0</version>
  </dependency>
</dependencies>

Aggiungi la chiave API all'app

Dopo aver aggiunto l'SDK Driver all'app, aggiungi la chiave API all'app. Devi utilizzare la chiave API del progetto che hai ottenuto durante la configurazione del progetto di sviluppo.

Questa sezione descrive come memorizzare la chiave API in modo che la tua app possa fare riferimento in modo più sicuro. Non dovresti controllare la chiave API nel tuo sistema di controllo della versione. Dovrebbe essere archiviato nel file local.properties, che si trova nella directory radice del progetto. Per ulteriori informazioni sul file local.properties, consulta la sezione File delle proprietà di Gradle.

Per semplificare questa attività, utilizza il plug-in Secrets Gradle per Android. Segui questa procedura per installare il plug-in Secrets Gradle e archiviare in modo sicuro la chiave API.

  1. Apri il file build.gradle di livello principale e aggiungi il seguente codice all'elemento dependencies in buildscript.

    Trendy

    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. Apri il file build.gradle a livello di app e aggiungi il seguente codice all'elemento plugins.

    Trendy

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

    Kotlin

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

  3. Sincronizza il tuo progetto con Gradle.

  4. Apri local.properties nella directory a livello di progetto, quindi aggiungi il codice seguente. Assicurati di sostituire YOUR_API_KEY con la tua chiave API.

    MAPS_API_KEY=YOUR_API_KEY

  5. Nel file AndroidManifest.xml, vai a com.google.android.geo.API_KEY e aggiorna l'attributo android:value come segue:

    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

L'esempio seguente mostra un manifest completo per un'app di esempio:

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

Includi le attribuzioni richieste nella tua app

Se utilizzi l'SDK Driver nella tua app, devi includere il testo dell'attribuzione e le licenze open source nella sezione Note legali dell'app. È preferibile includere le attribuzioni come voce di menu indipendente o come parte di una voce di menu Informazioni.

Le informazioni sulle licenze sono disponibili nel file "third_party_licenses.txt" del file AAR non archiviato.

Per informazioni su come includere notifiche open source, consulta la pagina https://developers.google.com/android/guides/opensource.

Dipendenze

L'SDK Driver utilizza gRPC per comunicare con il server Fleet Engine. Se non introduci già gRPC, potresti dover dichiarare le seguenti dipendenze:

dependencies {
    implementation 'io.grpc:grpc-android:1.12.0'
    implementation 'io.grpc:grpc-okhttp:1.12.0'
}

Senza queste dipendenze, l'SDK Driver potrebbe riscontrare errori in fase di runtime durante il tentativo di comunicare con il server Fleet Engine.

Se utilizzi ProGuard per ottimizzare le build, potrebbe essere necessario aggiungere le seguenti righe al file di configurazione di ProGuard:

-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**

Il livello API minimo supportato è 23.

Inizializza l'SDK

Per inizializzare l'oggetto DriverContext è necessario un ID provider (di solito l'ID progetto Google Cloud). Per ulteriori dettagli sulla configurazione del progetto Google Cloud, consulta Autenticazione e autorizzazione.

Prima di utilizzare l'SDK Driver, devi inizializzarlo. Per inizializzare l'SDK:

  1. Ottieni un oggetto Navigator da NavigationApi.

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

  2. Crea un oggetto DriverContext, compilando i campi obbligatori.

    DriverContext driverContext = DriverContext.builder(application)
    .setProviderId(providerId)
    .setVehicleId(vehicleId)
    .setAuthTokenFactory(authTokenFactory)
    .setNavigator(navigator)
    .setRoadSnappedLocationProvider(
        NavigationApi.getRoadSnappedLocationProvider(application))
    .build();

  3. Usa l'oggetto DriverContext per inizializzare *DriverApi.

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);

  4. Ottieni DeliveryVehicleReporter dall'oggetto API. (DeliveryVehicleReporter estende NavigationVehicleReporter.)

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();

Autenticazione con AuthTokenFactory

Quando l'SDK Driver genera aggiornamenti di posizione, deve inviarli al server Fleet Engine. Per autenticare queste richieste, l'SDK Driver chiama un'istanza di AuthTokenFactory fornita dal chiamante. Il produttore è responsabile della generazione dei token di autenticazione al momento dell'aggiornamento della località.

Il modo esatto in cui vengono generati i token è specifico per la situazione di ogni sviluppatore. Tuttavia, è probabile che l'implementazione debba:

  • recuperare un token di autenticazione, possibilmente in formato JSON, da un server HTTPS
  • analizzare e memorizzare nella cache il token
  • aggiorna il token alla scadenza

Per i dettagli sui token previsti dal server Fleet Engine, consulta Creazione di un token JWT (JSON Web Token) per l'autorizzazione.

Di seguito è riportata una bozza di implementazione di AuthTokenFactory:

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String vehicleServiceToken;  // 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(vehicleId);
    }
    if (ServiceType.VEHICLE.equals(authTokenContext.getServiceType)) {
      return vehicleServiceToken;
    } else {
      throw new RuntimeException("Unsupported ServiceType: " + authTokenContext.getServiceType());
    }
  }

  private void fetchNewToken(String vehicleId) {
    String url = "https://yourauthserver.example/token/" + vehicleId;

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      vehicleServiceToken = obj.get("VehicleServiceToken").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);
    }
  }
}

Questa particolare implementazione utilizza il client HTTP Java integrato per recuperare un token in formato JSON dal server di autenticazione dello sviluppatore. Il token viene salvato per essere riutilizzato. Il token viene recuperato nuovamente se il token precedente è trascorso entro 10 minuti dalla scadenza.

La tua implementazione potrebbe fare cose diverse, ad esempio usare un thread in background per aggiornare i token.

Le eccezioni in AuthTokenFactory vengono trattate come temporanee, a meno che non si verifichino ripetutamente. Dopo un certo numero di tentativi, l'SDK Driver presume che l'errore sia permanente e interrompe i tentativi di invio degli aggiornamenti.

Stato ed Error Reporting con StatusListener

Poiché l'SDK Driver esegue azioni in background, utilizza StatusListener per attivare le notifiche quando si verificano determinati eventi, come errori, avvisi o messaggi di debug. Gli errori possono essere di natura temporanea (ad esempio BACKEND_CONNECTIVITY_ERROR) oppure causare l'interruzione definitiva degli aggiornamenti della posizione (ad esempio VEHICLE_NOT_FOUND, indicando un errore di configurazione).

Devi fornire un'implementazione StatusListener facoltativa come la seguente:

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

Note su SSL/TLS

Internamente, l'implementazione dell'SDK di Driver utilizza SSL/TLS per comunicare in modo sicuro con il server Fleet Engine. Le versioni precedenti di Android (API 23 o precedenti) potrebbero richiedere una patch SecurityProvider per comunicare con il server. Per maggiori informazioni sull'utilizzo di SSL in Android, consulta Provider GMS per la sicurezza. L'articolo contiene anche esempi di codice per l'applicazione di patch al provider di sicurezza.

Attiva aggiornamenti posizione

Una volta creata un'istanza *VehicleReporter, l'attivazione degli aggiornamenti della posizione è semplice:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Gli aggiornamenti della posizione vengono inviati a intervalli regolari, se possibile. Ogni aggiornamento di posizione indica inoltre che il veicolo è online.

Per impostazione predefinita, l'intervallo di report è di 10 secondi. Puoi modificare l'intervallo dei report con reporter.setLocationReportingInterval(long, TimeUnit). L'intervallo di aggiornamento minimo supportato è di 5 secondi. Aggiornamenti più frequenti possono ridurre le richieste e gli errori.

Disattivare gli aggiornamenti della posizione

Quando il turno del conducente è finito, puoi interrompere gli aggiornamenti della posizione chiamando DeliveryVehicleReporter.disableLocationTracking.

Casi d'uso di modelli attendibili

Questa sezione descrive come utilizzare l'SDK Driver per implementare casi d'uso comuni quando si utilizza il modello attendibile.

Crea un veicolo

Puoi creare un veicolo dall'SDK Driver.

Prima di creare un veicolo, assicurati di inizializzare l'API Delivery Driver. L'ID veicolo deve essere creato con l'ID veicolo e fornitore utilizzato durante l'inizializzazione dell'SDK Driver. Poi crea il veicolo come mostrato nell'esempio seguente:

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
  DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
  // Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
  // Handle CreateVehicleRequest error.
}

Creare un'attività di ritiro della spedizione

Puoi creare un'attività di ritiro in spedizione dall'SDK Driver.

Prima di creare un'attività, assicurati di inizializzare l'API Delivery Driver. L'attività deve essere creata utilizzando l'ID provider specificato durante l'inizializzazione dell'SDK Driver. Quindi, crea l'attività di ritiro della spedizione come mostrato nell'esempio seguente. Per informazioni sugli ID attività, consulta gli esempi di ID attività.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_PICKUP)
   .build();

try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Crea un'attività di consegna della spedizione

Puoi creare un'attività di consegna in caso di spedizione dall'SDK Driver.

Prima di creare un'attività, assicurati di inizializzare l'API Delivery Driver. Quindi, crea l'attività di consegna della spedizione come illustrato nell'esempio seguente. Per informazioni sugli ID attività, consulta gli esempi di ID attività.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_DELIVERY)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Indisponibilità pianificata

Puoi creare un'attività che indica la non disponibilità (ad esempio per freni autisti o rifornimento di veicoli) dall'SDK Driver. Un'attività pianificata non disponibilità non deve includere un ID monitoraggio. Se vuoi, puoi fornire una località.

Prima di creare un'attività, assicurati di inizializzare l'API Delivery Driver. Quindi crea l'attività Non disponibilità come mostrato nell'esempio seguente. Per informazioni sugli ID attività, consulta gli esempi di ID attività.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setTaskDurationSeconds(2 * 60) // Duration or location (or both) must be provided for a BREAK task.
   .setTaskType(TaskType.UNAVAILABLE)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

Fermate programmate

Puoi creare un'attività di interruzione pianificata dall'SDK di Driver. Un'attività con interruzione pianificata potrebbe non includere un ID monitoraggio.

Prima di creare un'attività, assicurati di inizializzare l'API Delivery Driver. Quindi, crea l'attività di interruzione pianificata come mostrato nell'esempio seguente. Per informazioni sugli ID attività, consulta gli esempi di ID attività.

    static final String TASK_ID = "task-8241890"; //  Avoid auto-incrementing IDs.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
    CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
       .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
       .setTaskDurationSeconds(2 * 60)
       .setTaskType(TaskType.DELIVERY_SCHEDULED_STOP)
       .build();
    try {
       DeliveryTask task = taskManager.createTask(request).get();
       // Handle CreateTaskRequest DeliveryTask response.
    } catch (Exception e)  {
       // Handle CreateTaskRequest error.
    }

Aggiorna ordinamento delle attività

Puoi aggiornare l'ordine di esecuzione delle attività assegnate a un veicolo dall'SDK Driver.

L'aggiornamento dell'ordinamento delle attività assegna anche attività a un veicolo se non erano state precedentemente assegnate a un veicolo. Inoltre, consente di chiudere le attività precedentemente assegnate a un veicolo e escluse dall'ordine aggiornato. L'assegnazione di un'attività a un altro veicolo se era stata precedentemente assegnata a un altro veicolo genera un errore. Prima di assegnare un'attività al nuovo veicolo, chiudi l'attività esistente e creane una nuova.

Puoi aggiornare l'ordinamento delle attività in qualsiasi momento.

Prima di aggiornare l'ordinamento delle attività per un veicolo, assicurati che il veicolo e le attività siano già stati creati in Fleet Engine. Poi aggiorna l'ordinamento delle attività per il veicolo come mostrato nell'esempio seguente.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    try {
       List<VehicleStop> stops = reporter.setVehicleStops(
         ImmutableList.of(
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.ARRIVED)
                 .setWaypoint(Waypoint.builder().setLatLng(37.1749, 122.412).build())
                 .setTasks(ImmutableList.of(task1)) // Previously created DeliveryTask in Fleet Engine.
                 .build(),
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.NEW) // The current vehicle stop.
                 .setWaypoint(Waypoint.builder().setLatLng(37.7749, 122.4194).build())
                 .setTasks(ImmutableList.of(task2)) // Previously created DeliveryTask in Fleet Engine.
                 .build(),
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.NEW)
                 .setWaypoint(Waypoint.builder().setLatLng(37.3382, 121.8863).build())
                 .setTasks(ImmutableList.of(task3, task4)) // Previously created DeliveryTasks in Fleet Engine.
                 .build())).get();
       // Successfully updated vehicle stops in Fleet Engine. Returns the successfully set VehicleStops.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Setting VehicleStops must be attempted again after resolving
       // errors.
    }

Potrebbe verificarsi un'eccezione che potrebbe impedire un aggiornamento dello stato interno dell'SDK Driver. In questo caso, risolvi il problema e chiama di nuovo il numero setVehicleStops finché la chiamata non va a buon fine.

I potenziali problemi possono includere:

  • I VehicleStops specificati non seguono un pattern valido. Solo il primo VehicleStop può essere in uno qualsiasi dei VehicleStopStates: NEW, ENROUTE o ARRIVED. Gli arresti del veicolo dopo l'attuale fermata devono essere nel NUOVO stato VehicleStopState.

  • Le attività non esistono oppure appartengono a un altro veicolo.

  • Il veicolo non esiste.

Il veicolo è in linea con la prossima fermata

Fleet Engine deve ricevere una notifica quando un veicolo parte da una fermata e quando inizia la navigazione. Puoi inviare una notifica a Fleet Engine dall'SDK Driver.

Prima di comunicare a Fleet Engine che un veicolo è partito da una fermata, assicurati che le fermate del veicolo siano state create e impostate. Poi comunica a Fleet Engine la partenza del veicolo come mostrato nell'esempio seguente.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    reporter.enableLocationTracking(); // Location tracking must be enabled.

    // Create Vehicle, VehicleStops, and DeliveryTasks.
    // Set VehicleStops on Vehicle.

    navigator.setDestination(vehicleStop.getWaypoint());
    try {
       List<VehicleStop> updatedStops = reporter.enrouteToNextStop().get();
       // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
       // VehicleStop updated to ENROUTE state.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
       // after resolving errors.
    }

Potrebbe verificarsi un'eccezione che potrebbe impedire un aggiornamento dello stato interno dell'SDK Driver. In questo caso, risolvi il problema e chiama di nuovo enrouteToNextStop finché l'operazione non va a buon fine.

I potenziali problemi possono includere:

  • Nessun elemento VehicleStops rimanente impostato nell'SDK Driver.

Il veicolo arriva a una fermata

Fleet Engine deve ricevere una notifica quando un veicolo arriva a un fermo. Puoi inviare una notifica a Fleet Engine dall'SDK Driver.

Prima di comunicare a Fleet Engine che un veicolo è arrivato in una fermata, assicurati che le fermate del veicolo siano state impostate. Poi comunica a Fleet Engine l'arrivo del veicolo alla fermata, come mostrato nell'esempio seguente.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
// Mark ENROUTE to VehicleStop and start guidance using Navigator.

try {
   List<VehicleStop> updatedStopsArrived = reporter.arrivedAtStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ARRIVED state.
   navigator.clearDestinations();
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

Può verificarsi un'eccezione che potrebbe impedire un aggiornamento dello stato interno dell'SDK Driver. In questo caso, risolvi il problema e chiama di nuovo arrivedAtStop finché l'operazione non va a buon fine.

I potenziali problemi potrebbero includere:

  • Nessun elemento VehicleStops rimanente impostato nell'SDK Driver.

Il veicolo completa una fermata

Devi inviare una notifica a Fleet Engine quando un veicolo completa un'arresto. In questa notifica tutte le attività associate alla fermata vengono impostate sullo stato CHIUSO. Puoi inviare una notifica a Fleet Engine dall'SDK Driver.

Comunica a Fleet Engine che il veicolo ha completato il fermo veicolo, come mostrato nell'esempio seguente.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    reporter.enableLocationTracking(); // Location tracking must be enabled.

    // After completing the tasks at the VehicleStop, remove it from the
    // the current list of VehicleStops.

    try {
       List<VehicleStop> updatedStopsCompleted = reporter.completedStop().get();
       // Successfully updated vehicle stops in Fleet Engine. All tasks on the completed stop are set to CLOSED.
       // Returns the set VehicleStops, with the completed VehicleStop removed from the remaining list.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
       // after resolving errors.
    }

Può verificarsi un'eccezione che potrebbe impedire un aggiornamento dello stato interno dell'SDK Driver. In questo caso, risolvi il problema e chiama di nuovo completedStop finché l'operazione non va a buon fine.

I potenziali problemi possono includere:

  • Nessun elemento VehicleStops rimanente impostato nell'SDK Driver.

Chiudere un'attività

Per chiudere un'attività assegnata a un veicolo, informa Fleet Engine che il veicolo ha completato l'arresto in cui si svolge l'attività oppure rimuovilo dall'elenco delle fermate del veicolo. A questo scopo, puoi impostare l'elenco delle fermate rimanenti del veicolo proprio come per aggiornare l'ordine delle attività per un veicolo.

Se a un'attività non è ancora stato assegnato un veicolo e deve essere chiuso, aggiorna l'attività allo stato CHIUSA. Tuttavia, non puoi riaprire un'attività CHIUSA.

La chiusura di un'attività non indica l'esito positivo o negativo. Indica che l'attività non è più considerata in corso. Per il monitoraggio della spedizione, è importante indicare il risultato effettivo di un'attività in modo da poter mostrare il risultato della consegna.

Un'attività deve essere assegnata a un veicolo per poter usare l'SDK Driver per chiuderla. Per chiudere un'attività assegnata a un veicolo, informa Fleet Engine che il veicolo ha completato l'arresto in cui si svolge l'attività.

In alternativa, aggiorna l'ordine delle attività del veicolo a cui è assegnata l'attività, quindi rimuovi l'attività dall'elenco delle fermate.

Imposta il risultato dell'attività e la sua posizione

La chiusura di un'attività non indica l'esito positivo o negativo. Indica che l'attività non è più considerata in corso. Per il monitoraggio della spedizione, è importante indicare il risultato effettivo di un'attività in modo che possa essere mostrato il risultato della consegna e la fatturazione corretta per i servizi. Una volta impostato, non puoi modificare il risultato dell'attività. Puoi però modificare l'ora e la località del risultato dell'attività dopo averle impostate.

Il risultato delle attività in stato CHIUSO può essere impostato su SUCCEEDED o FAILED. Fleet Engine addebita solo le attività di distribuzione con lo stato SUCCEEDED.

Quando contrassegni il risultato di un'attività, Fleet Engine compila automaticamente la posizione del risultato dell'attività con l'ultima posizione nota del veicolo. Puoi ignorare questo comportamento.

L'esempio seguente mostra come utilizzare l'SDK Driver per impostare un risultato e un timestamp di un'attività. Non puoi impostare la località del risultato dell'attività utilizzando l'SDK Driver.

    static final String TASK_ID = "task-8241890";

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryTaskManager taskManager = api.getDeliveryTaskManager();

    // Updating an existing DeliveryTask which is already CLOSED. Manually
    // setting TaskOutcomeLocation with Driver SDK is not supported at this time.
    UpdateDeliveryTaskRequest req = UpdateDeliveryTaskRequest.builder(TASK_ID)
        .setTaskOutcome(TaskOutcome.SUCCEEDED)
        .setTaskOutcomeTimestamp(now()) // Timestamp in milliseconds.
        .build();

    try {
       DeliveryTask updatedTask = taskManager.updateTask(req);
       // Handle UpdateTaskRequest DeliveryTask response.
    } catch (Exception e)  {
       // Handle UpdateTaskRequest error.
    }

Cercare un veicolo

Puoi cercare un veicolo nell'SDK Driver. Prima di cercare un veicolo, assicurati di inizializzare l'API Delivery Driver. Puoi quindi cercare il veicolo come mostrato nell'esempio seguente.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
    try {
       DeliveryVehicle vehicle = vehicleManager.getVehicle().get();
       // Handle GetVehicleRequest DeliveryVehicle response.
    } catch (Exception e)  {
       // Handle GetVehicleRequest error.
    }

DeliveryVehicleManager può cercare solo DeliveryVehicle l'ID veicolo che è stato fornito durante l'inizializzazione dell'API Delivery Driver.