Pierwsze kroki z pakietem SDK Driver na Androida

Minimalne wymagania systemowe

Na urządzeniu mobilnym musi być zainstalowany Android 5.0 (poziom interfejsu API 21) lub nowszy.

Konfiguracja Maven

Pakiet SDK sterowników w wersji 4.99 i nowszych jest dostępny w repozytorium Google Maven.

Gradle

Dodaj do pliku build.gradle te informacje:

repositories {
    ...
    google()
}

Maven

Dodaj do pliku pom.xml te informacje:

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

Konfiguracja projektu

Aby korzystać z pakietu Driver SDK, Twoja aplikacja musi być kierowana na minSdkVersion w wersji 21 lub nowszej. Więcej informacji znajdziesz w informacjach o wersji.

Aby uruchomić aplikację stworzoną za pomocą pakietu Driver SDK, na urządzeniu z Androidem muszą być zainstalowane Usługi Google Play.

Konfigurowanie projektu programistycznego

Aby skonfigurować projekt programistyczny i uzyskać jego klucz interfejsu API w konsoli Google Cloud:

  1. Utwórz nowy projekt Google Cloud Console lub wybierz istniejący projekt do użycia z pakietem Driver SDK. Zaczekaj kilka minut, aż nowy projekt pojawi się w konsoli Google Cloud.

  2. Aby uruchomić aplikację demonstracyjną, projekt musi mieć dostęp do pakietu Maps SDK na Androida. W konsoli Google Cloud wybierz Interfejsy API i usługi > Biblioteka, a następnie wyszukaj i włącz pakiet SDK Map Google na Androida.

  3. Aby uzyskać klucz interfejsu API projektu, wybierz Interfejsy API i usługi > Dane logowania > Utwórz dane logowania > Klucz interfejsu API. Więcej informacji o uzyskiwaniu klucza interfejsu API znajdziesz w artykule Uzyskiwanie klucza interfejsu API.

Dodaj do aplikacji pakiet SDK Driver

Pakiet SDK sterownika jest dostępny w prywatnym repozytorium Maven. Repozytorium zawiera pliki modelu obiektu projektu (.pom) z pakietu SDK i dokumenty Javadocs. Aby dodać Driver SDK do aplikacji:

  1. Dodaj podaną niżej zależność do konfiguracji Gradle lub Maven, zastępując zmienną VERSION_NUMBER odpowiednią wersją pakietu Driver SDK.

    Gradle

    Dodaj do konta build.gradle:

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

    Maven

    Dodaj do konta pom.xml:

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

Dodawanie klucza interfejsu API do aplikacji

Po dodaniu pakietu SDK sterownika do aplikacji dodaj do niej klucz interfejsu API. Musisz użyć klucza interfejsu API projektu uzyskanego podczas konfigurowania projektu programistycznego.

Z tej sekcji dowiesz się, jak przechowywać klucz interfejsu API, aby można było bezpieczniej się do niego odwoływać w aplikacji. Nie sprawdzaj klucza interfejsu API w systemie kontroli wersji. Powinien znajdować się w pliku local.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku local.properties znajdziesz w artykule Pliki właściwości Gradle.

Aby ułatwić sobie to zadanie, wykorzystaj wtyczkę Gradle obiektów tajnych na Androida. Wykonaj tę procedurę, aby zainstalować wtyczkę do obsługi obiektów tajnych do Gradle i bezpiecznie przechowywać klucz interfejsu API.

  1. Otwórz plik build.gradle głównego poziomu i dodaj ten kod do elementu dependencies w obszarze buildscript.

    Zakręcony

    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. Otwórz plik build.gradle na poziomie aplikacji i dodaj do elementu plugins poniższy kod.

    Zakręcony

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

    Kotlin

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

  3. Zsynchronizuj projekt z Gradle.

  4. Otwórz local.properties w katalogu na poziomie projektu, a następnie dodaj ten kod. Pamiętaj, aby zastąpić YOUR_API_KEY swoim kluczem interfejsu API.

    MAPS_API_KEY=YOUR_API_KEY

  5. W pliku AndroidManifest.xml przejdź do com.google.android.geo.API_KEY i zaktualizuj atrybut android:value w ten sposób:

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

Ten przykład przedstawia pełny plik manifestu przykładowej aplikacji:

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

Uwzględnij wymagane informacje o atrybucji w aplikacji

Jeśli korzystasz w aplikacji z pakietu Driver SDK, w sekcji informacji prawnych dotyczących aplikacji musisz umieścić tekst źródła oraz licencje open source. Informacje o autorach najlepiej dodać jako niezależne pozycje w menu lub pozycję Informacje.

Wymagany tekst atrybucji i licencje open source znajdziesz w pliku ZIP z pakietem Driver SDK:

  • NOTICE.txt
  • LICENSES.txt

Zależności

Pakiet SDK sterownika używa gRPC do komunikacji z serwerem Fleet Engine. Jeśli nie masz jeszcze wywołania gRPC, konieczne może być zadeklarowanie tych zależności:

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

Bez tych zależności pakiet SDK sterownika napotyka błędy w czasie działania podczas próby komunikacji z serwerem Fleet Engine.

Jeśli do optymalizowania kompilacji używasz ProGuard, do pliku konfiguracji ProGuard może być konieczne dodanie tych wierszy:

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

Minimalny obsługiwany poziom interfejsu API to 21.

Inicjowanie pakietu SDK

Do zainicjowania obiektu DriverContext wymagany jest identyfikator dostawcy (zwykle identyfikator projektu Google Cloud). Więcej informacji o konfigurowaniu projektu Google Cloud znajdziesz w artykule Uwierzytelnianie i autoryzacja.

Przed użyciem pakietu Driver SDK musisz najpierw zainicjować ten pakiet. Aby zainicjować pakiet SDK:

  1. Uzyskaj obiekt Navigator z 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. Utwórz obiekt DriverContext i wypełnij wymagane pola.

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

  3. Użyj obiektu DriverContext do zainicjowania *DriverApi.

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);

  4. Pobierz DeliveryVehicleReporter z obiektu API. (DeliveryVehicleReporter powoduje rozszerzenie NavigationVehicleReporter).

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();

Uwierzytelniam w sieci AuthTokenFactory

Gdy pakiet Driver SDK generuje aktualizacje lokalizacji, musi je wysłać do serwera Fleet Engine. Aby uwierzytelnić te żądania, pakiet SDK sterowników wywoła metodę AuthTokenFactory dostarczaną przez element wywołujący. Fabryka jest odpowiedzialna za generowanie tokenów uwierzytelniania w czasie aktualizacji lokalizacji.

Sposób generowania tokenów zależy od sytuacji każdego dewelopera. Jednak wdrożenie prawdopodobnie będzie wymagało:

  • pobranie tokena uwierzytelniania, np. w formacie JSON, z serwera HTTPS;
  • analizowanie i zapisywanie tokena w pamięci podręcznej
  • odśwież token, gdy straci ważność

Informacje o tokenach, których oczekuje serwer Fleet Engine, znajdziesz w sekcji Tworzenie tokena internetowego JSON (JWT) do autoryzacji.

Oto szkielet implementacji obiektu 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);
    }
  }
}

W tej implementacji używa on wbudowanego klienta HTTP Java do pobierania tokena w formacie JSON z serwera uwierzytelniania dewelopera. Token zostaje zapisany do ponownego użycia. Token jest pobierany ponownie, jeśli do wygaśnięcia starego tokena minęło 10 minut.

Twoja implementacja może działać inaczej, np. używać wątku w tle do odświeżania tokenów.

Wyjątki w AuthTokenFactory będą traktowane jako przejściowe, chyba że będą się powtarzać. Po kilku próbach pakiet SDK sterownika założy, że błąd jest trwały, i przestanie próbować wysyłać aktualizacje.

Raportowanie stanu i błędów w StatusListener

Ponieważ pakiet SDK sterownika wykonuje działania w tle, używaj interfejsu StatusListener do wywoływania powiadomień po wystąpieniu określonych zdarzeń, np. błędów, ostrzeżeń czy komunikatów debugowania. Błędy mogą być przejściowe (np. BACKEND_CONNECTIVITY_ERROR) lub powodować trwałe zatrzymanie aktualizacji lokalizacji (np. VEHICLE_NOT_FOUND, co wskazuje na błąd konfiguracji).

Podajesz opcjonalną implementację StatusListener, taką jak:

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

Uwagi na temat SSL/TLS

Wewnętrznie implementacja pakietu Driver SDK używa SSL/TLS do bezpiecznej komunikacji z serwerem Fleet Engine. Starsze wersje Androida (interfejsy API w wersji 21 lub starszej) mogą wymagać poprawki SecurityProvider, aby mogły komunikować się z serwerem. Więcej informacji o korzystaniu z protokołu SSL na Androidzie znajdziesz w tym artykule. Artykuł zawiera też przykładowy kod do zainstalowania poprawek u dostawcy zabezpieczeń.

Włączam aktualizacje lokalizacji

Gdy masz instancję *VehicleReporter, włączenie aktualizacji lokalizacji jest proste:

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

Aktualizacje lokalizacji będą wysyłane w regularnych odstępach czasu, o ile będzie to możliwe. Każda aktualizacja lokalizacji będzie też wskazywać, że pojazd jest online.

Domyślna częstotliwość raportowania wynosi 10 sekund. Okres raportowania można zmienić za pomocą opcji reporter.setLocationReportingInterval(long, TimeUnit). Minimalny obsługiwany odstęp czasu między aktualizacjami to 5 sekund. Częstsze aktualizacje mogą powodować wolniejsze przesyłanie żądań i błędów.

Wyłączanie aktualizacji lokalizacji

Po zakończeniu pracy kierowcy aktualizacje lokalizacji możesz zatrzymać, dzwoniąc do: DeliveryVehicleReporter.disableLocationTracking.

Przypadki użycia zaufanego modelu

W tej sekcji dowiesz się, jak za pomocą pakietu SDK sterownika zaimplementować typowe przypadki użycia przy użyciu modelu zaufanego.

Utwórz pojazd

Możesz utworzyć pojazd za pomocą pakietu Driver SDK.

Zanim utworzysz pojazd, zainicjuj interfejs Delivery Driver API. Identyfikator pojazdu należy utworzyć z identyfikatorem pojazdu i dostawcy użytymi podczas inicjowania pakietu SDK kierowcy. Następnie utwórz pojazd, tak jak w tym przykładzie:

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

Utwórz zadanie odbioru przesyłki

Zadanie odbioru przesyłki możesz utworzyć w pakiecie Driver SDK.

Zanim utworzysz zadanie, zainicjuj interfejs Delivery Driver API. Zadanie należy utworzyć przy użyciu identyfikatora dostawcy podanego podczas inicjowania pakietu SDK sterownika. Następnie utwórz zadanie odbioru przesyłki w podany niżej przykład. Informacje o identyfikatorach zadań znajdziesz w sekcji Przykłady identyfikatorów zadań (w języku angielskim).

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

Tworzenie zadania dostawy przesyłki

Zadanie dostawy przesyłki możesz utworzyć w pakiecie Driver SDK.

Zanim utworzysz zadanie, zainicjuj interfejs Delivery Driver API. Następnie utwórz zadanie dostawy zgodnie z poniższym przykładem. Informacje o identyfikatorach zadań znajdziesz w artykule Przykłady identyfikatorów zadań.

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

Zaplanowana niedostępność

Możesz utworzyć zadanie wskazujące niedostępność (np. w przypadku kierowców lub tankowania pojazdów) z pakietu SDK Driver SDK. Zaplanowane zadanie niedostępności nie może zawierać identyfikatora śledzenia. Opcjonalnie możesz podać lokalizację.

Zanim utworzysz zadanie, zainicjuj interfejs Delivery Driver API. Następnie utwórz zadanie związane z niedostępnością w sposób podany w poniższym przykładzie. Informacje o identyfikatorach zadań znajdziesz w artykule Przykłady identyfikatorów zadań.

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

Zaplanowane przystanki

Zaplanowane zadanie zatrzymania możesz utworzyć w pakiecie SDK sterownika. Zaplanowane zadanie zatrzymania może nie zawierać identyfikatora śledzenia.

Zanim utworzysz zadanie, zainicjuj interfejs Delivery Driver API. Następnie utwórz zaplanowane zatrzymanie w sposób podany w poniższym przykładzie. Informacje o identyfikatorach zadań znajdziesz w artykule Przykłady identyfikatorów zadań.

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

Zaktualizuj kolejność zadań

Możesz zaktualizować kolejność wykonywania zadań przypisanych do pojazdu za pomocą pakietu SDK sterownika.

Zaktualizowanie kolejności zadań powoduje też przypisanie do pojazdu zadań, które nie zostały wcześniej przypisane do pojazdu. Zamykają też zadania, które zostały wcześniej przypisane do pojazdu i pominięte w zaktualizowanej kolejności. Przypisanie zadania do innego pojazdu, jeśli zostało ono wcześniej przypisane do innego pojazdu, spowoduje wystąpienie błędu. Przed przypisaniem zadania do nowego pojazdu zamknij istniejące zadanie, a następnie utwórz nowe.

Kolejność zadań możesz zmienić w każdej chwili.

Zanim zaktualizujesz kolejność zadań w pojeździe, upewnij się, że pojazd i zadania zostały już utworzone we Fleet Engine. Następnie zaktualizuj kolejność zadań w pojeździe, jak pokazano w przykładzie poniżej.

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

Wyjątek może uniemożliwiać aktualizację stanu wewnętrznego pakietu SDK sterownika. Jeśli tak się stanie, rozwiąż problem, a następnie wywołuj ponownie setVehicleStops, aż połączenie się powiedzie.

Możliwe problemy:

  • Podane wartości VehicleStops są niezgodne z prawidłowym wzorcem. Tylko pierwszy pojazd może mieć wartość VehicleStopStates: NEW, ENROUTE lub ARRIVED. Wartość VehicleStops po bieżącym przystanku musi mieć wartość NEW VehicleStopState.

  • Zadania nie istnieją lub należą do innego pojazdu.

  • Pojazd nie istnieje.

Pojazd jedzie do następnego przystanku

Usługa Fleet Engine musi być powiadamiana o tym, że pojazd wychodzi ze postoju i rozpoczyna nawigację. Możesz powiadomić Fleet Engine za pomocą pakietu SDK sterownika.

Zanim powiadomisz Fleet Engine o opuszczeniu postoju, upewnij się, że został on utworzony i ustawiony. Następnie powiadom Fleet Engine o odjazdu pojazdu, jak pokazano w poniższym przykładzie.

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

Może wystąpić wyjątek, który uniemożliwia aktualizację stanu wewnętrznego pakietu SDK sterownika. Jeśli tak się stanie, rozwiąż problem, a potem jeszcze raz wywołaj funkcję enrouteToNextStop, aż operacja się powiedzie.

Możliwe problemy:

  • W pakiecie Driver SDK nie ustawiono żadnych innych funkcji (VehicleStops).

Pojazd wjeżdżający na przystanek

Usługa Fleet Engine musi być powiadamiana, gdy pojazd się zatrzyma. Powiadomień Fleet Engine możesz przesłać za pomocą pakietu SDK sterowników.

Zanim powiadomisz Fleet Engine o zatrzymaniu pojazdu, upewnij się, że został on ustawiony. Następnie powiadom Fleet Engine o dotarciu pojazdu do celu, tak jak w przykładzie poniżej.

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

Wyjątek może uniemożliwiać aktualizację stanu wewnętrznego pakietu SDK sterownika. W takim przypadku rozwiąż problem, a potem jeszcze raz wywołuj metodę arrivedAtStop, aż operacja się powiedzie.

Możliwe problemy:

  • W pakiecie Driver SDK nie ustawiono żadnych innych funkcji (VehicleStops).

Pojazd zatrzymuje się

Usługa Fleet Engine musi być powiadamiana o zatrzymaniu pojazdu. Spowoduje to ustawienie wszystkich zadań powiązanych z tym przystankiem w stanie ZAMKNIĘTE. Możesz to zrobić za pomocą pakietu SDK sterownika.

Powiadom Fleet Engine, że pojazd zakończył działanie VehicleStop, jak pokazano w poniższym przykładzie.

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

Wyjątek może uniemożliwiać aktualizację stanu wewnętrznego pakietu SDK sterownika. W takim przypadku rozwiąż problem, a potem jeszcze raz wywołuj metodę completedStop, aż operacja się powiedzie.

Możliwe problemy:

  • W pakiecie Driver SDK nie ustawiono żadnych innych funkcji (VehicleStops).

Zamykanie zadania

Aby zamknąć zadanie przypisane do pojazdu, możesz powiadomić Fleet Engine o tym, że pojazd zakończył postój, na którym to zadanie jest wykonywane, lub usunąć go z listy postojów. Aby to zrobić, możesz ustawić listę pozostałych pojazdów tak, jak przy aktualizowaniu kolejności zadań pojazdu.

Jeśli do zadania nie przypisano jeszcze pojazdu i trzeba je zamknąć, zmień jego stan na ZAMKNIĘTE. Nie możesz jednak ponownie otworzyć zadania ZAMKNIĘTE.

Zamknięcie zadania nie oznacza powodzenia ani niepowodzenia. Wskazuje on, że zadanie nie jest już uważane za w toku. W przypadku śledzenia przesyłki ważne jest wskazanie rzeczywistego wyniku zadania, aby można było poznać rezultat dostawy.

Aby można było je zamknąć za pomocą pakietu Driver SDK, należy przypisać je do pojazdu. Aby zamknąć zadanie przypisane do pojazdu, powiadom Fleet Engine, że pojazd zakończył postój, na którym to zadanie jest wykonywane.

Możesz też zaktualizować kolejność zadań pojazdu, do którego jest przypisane, a następnie usunąć wybrane zadanie z listy przystanków.

Ustawianie lokalizacji wyniku zadania i wyników

Zamknięcie zadania nie oznacza powodzenia ani niepowodzenia. Wskazuje on, że zadanie nie jest już uważane za w toku. W przypadku śledzenia przesyłki ważne jest, aby określić rzeczywisty wynik zadania, aby można było poznać wynik dostawy i naliczać odpowiednie opłaty za usługi. Po ustawieniu nie można zmienić wyniku zadania. Możesz jednak zmienić czas i lokalizację wyników zadania po ich ustawieniu.

Zadania ze stanem ZAMKNIĘTE mogą mieć wynik SUCCEEDED lub FAILED. Fleet Engine nalicza opłaty tylko za zadania związane z dostarczaniem o stanie SUCCEEDED.

Podczas zaznaczania wyniku zadania Fleet Engine automatycznie uzupełni lokalizację wyniku zadania ostatnią znaną lokalizacją pojazdu. Możesz zastąpić to działanie.

Z przykładu poniżej dowiesz się, jak za pomocą pakietu Driver SDK ustawić wynik zadania i sygnaturę czasową. Nie możesz ustawić lokalizacji wyniku zadania za pomocą pakietu Driver SDK.

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

Wyszukiwanie pojazdu

Pojazd możesz wyszukać za pomocą pakietu Driver SDK. Zanim wyszukasz pojazd, zainicjuj interfejs Delivery Driver API. Następnie możesz wyszukać pojazd zgodnie z przykładem poniżej.

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 może wyszukać obiekt DeliveryVehicle tylko pod kątem identyfikatora pojazdu podanego podczas inicjowania interfejsu Delivery Driver API.