Pakiet SDK dla klientów indywidualnych na Androida

Za pomocą pakietu SDK konsumentów możesz tworzyć i uruchamiać podstawową aplikację dla klientów indywidualnych zintegrowaną z usługami backendu oferującymi przejazdy i dostawy. Możesz utworzyć aplikację Podróże i zamówienia, która może wyświetlać aktywną podróż, odpowiadać na jej aktualizacje i obsługiwać błędy.

Ponieważ pakiet SDK klienta jest architekturą modułową, możesz używać części interfejsu API, których chcesz używać w przypadku konkretnej aplikacji, i integrować je z własnymi interfejsami API, usługami backendu Fleet Engine oraz interfejsami API Google Maps Platform.

Minimalne wymagania systemowe

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

Wymagania wstępne

Pakiety SDK Transportu i Logistyki na Androida są publikowane w repozytorium Artifact Registry Maven. Repozytorium obejmuje pliki Project Object Model (.pom) pakietu SDK i pliki Java w trybie offline.

Uzyskaj dostęp

Jeśli korzystasz z Google Workspace, utwórz grupę Workspace, na przykład google-maps-platform-sdk-users@workspacedomain.com, podczas rejestracji i podaj jej nazwę Google. Jest to zalecane. Twoja grupa Workspace zostanie dodana do listy dozwolonych, która przyznaje dostęp do repozytorium Maven gmp-artifacts/transportation. Sprawdź, czy na liście znajdują się adresy e-mail użytkowników i konta usługi, które muszą mieć dostęp.

Jeśli Twoja organizacja nie może tworzyć grup Workspace, wyślij do Google listę adresów e-mail użytkowników i kont usługi, które potrzebują dostępu do tych artefaktów.

Programowanie lokalne

W przypadku programowania lokalnego wystarczy zalogować się za pomocą pakietu SDK Cloud.

gcloud auth login

Adres e-mail używany do logowania musi należeć do grupy Workspace.

Automatyzacja (systemy kompilacji lub tryb ciągłej integracji)

Skonfiguruj hosty automatyzacji zgodnie ze sprawdzonymi metodami:

• Jeśli proces działa w środowisku Google Cloud, skorzystaj z automatycznego wykrywania danych logowania.

• W przeciwnym razie zapisz plik klucza konta usługi w bezpiecznej lokalizacji w systemie plików hosta i ustaw odpowiednio zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS.

Adres e-mail konta usługi powiązany z danymi logowania musi być członkiem grupy Workspace.

Konfiguracja

Skonfiguruj Maven lub Gradle, aby automatycznie wykrywać dane logowania użytkowników lub usług.

plugins {
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.5"
}
repositories {
  maven {
    url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
  }
}

<repositories>
  <repository>
    <id>gmp-artifacts</id>
    <url>artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation</url>
    <releases>
      <enabled>true</enabled>
    </releases>
  </repository>
</repositories>
<build>
  <extensions>
    <extension>
      <groupId>com.google.cloud.artifactregistry</groupId>
      <artifactId>artifactregistry-maven-wagon</artifactId>
      <version>2.1.5</version>
    </extension>
  </extensions>
</build>

Więcej informacji o weryfikowaniu dostępu znajdziesz w artykule Zarządzanie pakietami Java.

Konfiguracja projektu

Aby korzystać z pakietu SDK dla Androida, Twoja aplikacja musi być kierowana na Androida w wersji minSdkVersion lub nowszej.

Aby uruchomić aplikację za pomocą pakietu SDK dla konsumentów, na urządzeniu z Androidem należy zainstalować Usługi Google Play.

Konfigurowanie projektu programistycznego

Aby skonfigurować projekt deweloperski i uzyskać klucz interfejsu API dla projektu w Google Cloud Console:

1. Utwórz nowy projekt Google Cloud Console lub wybierz istniejący, który będzie używany z pakietem SDK dla klientów indywidualnych. Zaczekaj kilka minut, aż nowy projekt pojawi się w konsoli Google Cloud.

2. Aby uruchomić aplikację w wersji demonstracyjnej, Twój projekt musi mieć dostęp do pakietu SDK Maps na Androida. W konsoli Google Cloud wybierz Interfejsy API i usługi > Biblioteka, a potem wyszukaj i włącz pakiet SDK Map 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 Pobieranie klucza interfejsu API.

Dodawanie do aplikacji pakietu SDK klienta

SDK klienta jest dostępny w prywatnym repozytorium Maven. Repozytorium zawiera pliki Project Object Model (.pom) pakietu SDK i pliki Javadocs. Aby dodać pakiet SDK do swojej aplikacji:

1. Skonfiguruj środowisko, aby uzyskać dostęp do repozytorium Maven w sposób opisany w sekcji Uzyskiwanie dostępu.

   Jeśli w deklaracji settings.gradle masz scentralizowaną konfigurację zarządzania zależnościami, wyłącz ją w ten sposób.

   • Usuń ten blok kodu w aplikacji settings.gradle:

     import org.gradle.api.initialization.resolve.RepositoriesMode
     dependencyResolutionManagement {
         repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
         repositories {
             google()
             mavenCentral()
         }
     }
     

2. Dodaj zależność do konfiguracji Gradle lub Maven, zastępując zmienną VERSION_NUMBER odpowiednią wersję pakietu SDK klienta.

   Gradle

   Dodaj do build.gradle:

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

   Maven

   Dodaj do pom.xml:

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

Dodawanie klucza interfejsu API do aplikacji

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

W tej sekcji opisano, jak przechowywać klucz interfejsu API, tak by można było bezpieczniej odwoływać się do niego w aplikacji. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji. Powinien być zapisany 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 uprościć to zadanie, możesz użyć wtyczki Gradle obiektów tajnych na Androida.

Aby zainstalować wtyczkę i zapisać klucz interfejsu API:

1. Otwórz plik build.gradle na poziomie katalogu głównego i dodaj ten kod do elementu dependencies w sekcji 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 ten kod.

   Zakręcony

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

   Kotlin

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

3. Jeśli używasz Android Studio, zsynchronizuj projekt z Gradle.

4. Otwórz local.properties w katalogu na poziomie projektu i dodaj ten kod. Zastąp 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 następujący sposób:

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

Poniższy przykład zawiera pełny plik manifestu przykładowej aplikacji:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.consumerapidemo">
    <uses-permission android:name="android.permission.ACCESS_FINE_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 atrybucje w aplikacji

Jeśli w swojej aplikacji korzystasz z pakietu SDK dla klientów indywidualnych, w sekcji Informacje prawne o jego aplikacji musisz umieścić tekst atrybucji oraz licencje open source. Atrybucja powinna znajdować się jako niezależna pozycja w menu lub jako część menu.

Wymagany tekst atrybucji oraz licencje open source znajdziesz w pliku ZIP z pakietem Ridesharing Consumer SDK:

• NOTICE.txt
• LICENSES.txt

Uwierzytelnianie SDK klienta

SDK klienta uwierzytelnia się za pomocą tokenów sieciowych JSON. Token internetowy JSON (JWT) to podstawowy token dostępu w formacie JSON, który zapewnia co najmniej 1 deklarację dotyczącą usługi. Serwer może na przykład wygenerować token zgłaszający, że jest „zalogowany jako administrator” i przekazać go klientowi. Klient może użyć tego tokena, aby potwierdzić, że jest zalogowany jako administrator.

SDK klienta używa tokena internetowego JSON udostępnionego przez aplikację do komunikacji z Fleet Engine. Więcej informacji znajdziesz w artykule Uwierzytelnianie i uwierzytelnianie Fleet Engine.

Token autoryzacji zapewnia dostęp do tych usług Fleet Engine:

• TripService – daje pakietowi SDK konsumenta dostęp do szczegółów podróży, w tym do pozycji pojazdu, trasy i szacowanego czasu dotarcia. Tokeny autoryzacji usługi podróży muszą zawierać w jego nagłówku authorization żądanie, gdzie TRIP_ID to identyfikator podróży.tripid:TRIP_ID
• VehicleService – dostarcza pakietowi SDK konsumentów informacje o lokalizacji fugo dla pojazdu, która służy do wyświetlania warstwy gęstości pojazdu i szacowania szacowanego czasu dotarcia punktu odbioru. Ponieważ pakiet SDK dla klientów indywidualnych korzysta z lokalizacji fuzz, tokeny autoryzacji usługi pojazdu nie wymagają roszczenia vehicleid.

Wywołania zwrotne tokena internetowego JSON

SDK klienta rejestruje wywołanie zwrotne tokena autoryzacji w aplikacji podczas inicjowania. SDK wywołuje aplikację, aby uzyskać token wszystkich żądań sieciowych, które wymagają autoryzacji.

Zdecydowanie zalecamy, aby tokeny autoryzacji implementacji wywołań zwrotnych zostały odświeżone i odświeżone tylko po upływie expiry. Tokeny należy wydawać z godziną wygaśnięcia.

Wywołanie zwrotne tokena autoryzacji określa, który token usługi jest potrzebny do korzystania z usługi TripService. Wskazuje także wymagany element tripId w kontekście.

Poniższy przykład kodu pokazuje, jak wdrożyć wywołanie zwrotne tokenu autoryzacji.

class JsonAuthTokenFactory implements AuthTokenFactory {

  private static final String TOKEN_URL =
      "https://yourauthserver.example/token";

  private static class CachedToken {
    String tokenValue;
    long expiryTimeMs;
    String tripId;
  }

  private CachedToken token;

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  @Override
  public String getToken(AuthTokenContext context) {
    // If there is no existing token or token has expired, go get a new one.
    String tripId = context.getTripId();
    if (tripId == null) {
      throw new RuntimeException("Trip ID is missing from AuthTokenContext");
    }
    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        !tripId.equals(token.tripId)) {
      token = fetchNewToken(tripId);
    }
    return token.tokenValue;
  }

  private static CachedToken fetchNewToken(String tripId) {
    String url = TOKEN_URL + "/" + tripId;
    CachedToken token = new CachedToken();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();

      token.tokenValue = obj.get("ServiceToken").getAsString();
      token.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 5 minutes from that time.
      */
      token.expiryTimeMs -= 5 * 60 * 1000;
    } catch (IOException e) {
      /*
      * It's OK to throw exceptions here. The error listeners will receive the
      * error thrown here.
      */
      throw new RuntimeException("Could not get auth token", e);
    }
    token.tripId = tripId;

    return token;
  }
}

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  override fun getToken(context: AuthTokenContext): String {
    // If there is no existing token or token has expired, go get a new one.
    val tripId = 
      context.getTripId() ?: 
        throw RuntimeException("Trip ID is missing from AuthTokenContext")

    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        tripId != token.tripId) {
      token = fetchNewToken(tripId)
    }

    return token.tokenValue
  }

  class CachedToken(
    var tokenValue: String? = "", 
    var expiryTimeMs: Long = 0,
    var tripId: String? = "",
  )

  private companion object {
    const val TOKEN_URL = "https://yourauthserver.example/token"

    fun fetchNewToken(tripId: String) {
      val url = "$TOKEN_URL/$tripId"
      val token = CachedToken()

      try {
        val reader = InputStreamReader(URL(url).openStream())

        reader.use {
          val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()

          token.tokenValue = obj.get("ServiceToken").getAsString()
          token.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 5 minutes from that time.
          */
          token.expiryTimeMs -= 5 * 60 * 1000
        }
      } catch (e: IOException) {
        /*
        * It's OK to throw exceptions here. The error listeners will receive the
        * error thrown here.
        */
        throw RuntimeException("Could not get auth token", e)
      }

      token.tripId = tripId

      return token
    }
  }
}

Inicjowanie interfejsu API

Przed wykonaniem tych procedur zakłada się, że zostały włączone odpowiednie usługi oraz pakiet SDK dla klientów indywidualnych.

Pobranie instancji ConsumerApi

Aby korzystać z pakietu SDK dla klientów indywidualnych, Twoja aplikacja musi zainicjować asynchroniczne polecenie ConsumerApi. Interfejs API to pojedynczy interfejs. Metoda inicjowania wymaga zdarzenia AuthTokenFactory. Fabryka generuje dla użytkownika nowe tokeny JWT w razie potrzeby.

providerId to identyfikator projektu Twojego projektu Google Cloud. Więcej informacji o tworzeniu projektu znajdziesz w przewodniku użytkownika Fleet Engine.

Aplikacja powinna wdrożyć właściwość AuthTokenFactory zgodnie z opisem w sekcji Uwierzytelnianie klienta SDK.

Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
    this, "myProviderId", authTokenFactory);

consumerApiTask.addOnSuccessListener(
  consumerApi -> this.consumerApi = consumerApi);

val consumerApiTask =
  ConsumerApi.initialize(this, "myProviderId", authTokenFactory)

consumerApiTask?.addOnSuccessListener { consumerApi: ConsumerApi ->
  this@YourActivity.consumerApi = consumerApi
}

Utwórz interfejs

Interfejs użytkownika aplikacji możesz utworzyć za pomocą ConsumerMapFragment lub ConsumerMapView. ConsumerMapFragment pozwala zdefiniować mapę za pomocą Fragment, a ConsumerMapView umożliwia użycie View. Funkcje wspólnej jazdy są takie same zarówno w ConsumerMapView, jak i w ConsumerMapFragment, więc możesz wybrać taki, który najlepiej pasuje do Twojej aplikacji: View czy Fragment.

Dodaj obsługę obiektów rysunkowych API 19 (KitKat) i wektorowych

Jeśli Twoja aplikacja wymaga obsługi urządzeń z interfejsem API 19 (KitKat) i elementów rysowalnych wektorowo, dodaj ten kod do swojej aktywności. Stosuje on teraz ten komponent AppCompatActivity, aby można było używać obiektów rysowalnych wektorowo w pakiecie SDK klienta.

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

Dodawanie fragmentu mapy lub widoku mapy

Ty tworzysz mapę do wyświetlania udostępniania ścieżki we fragmencie kodu Androida lub w widoku, który zdefiniujesz w pliku XML układu aplikacji (w lokalizacji /res/layout). Fragment (lub widok) zapewnia dostęp do mapy udostępniania ścieżki, którą aplikacja może otwierać i modyfikować. Mapa umożliwia też korzystanie z ConsumerController, co pozwala aplikacji na kontrolowanie i udostępnianie ustawień udostępniania podróży.

Mapa i kontroler udostępniania podróży

Mapę udostępniania ścieżki definiujesz jako fragment (przy użyciu obiektu ConsumerMapFragment) lub jako widok (przy użyciu właściwości ConsumerMapView), jak pokazano w poniższym przykładzie kodu. Następnie metoda onCreate() powinna wywołać metodę getConsumerGoogleMapAsync(callback), która asynchroniczne zwraca ConsumerGoogleMap w wywołaniu zwrotnym. Do udostępniania udostępniania dziennika służy interfejs ConsumerGoogleMap, który może być aktualizowany w zależności od aplikacji.

Fragment mapy konsumenta

Definiujesz fragment w pliku XML układu aplikacji, jak pokazano w poniższym przykładzie kodu.

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Wywołanie getConsumerGoogleMapAsync() powinno pochodzić z metody onCreate().

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

    // Find the ConsumerMapFragment.
    ConsumerMapFragment consumerMapFragment =
        (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

    // Initiate the callback that returns the map.
    if (consumerMapFragment != null) {
      consumerMapFragment.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          });
    }
  }

}

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    // Find the ConsumerMapFragment.
    val consumerMapFragment =
      fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

    consumerMapFragment.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      }
    )
  }
}

Widok mapy konsumenta

Tego widoku można użyć we fragmencie lub w działaniu, zgodnie z definicją w pliku XML.

<com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/consumer_map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Połączenie z numerem getConsumerGoogleMapAsync() powinno być wykonywane z poziomu urządzenia onCreate(). Oprócz parametru wywołania zwrotnego wymaga on zawartej w nim aktywności lub fragmentu i GoogleMapOptions (może mieć wartość null) o atrybutach konfiguracji MapView. Klasa lub zadanie podstawowe musi być komponentem FragmentActivity lub odpowiedniego typu Fragment, bo taki komponent zapewnia dostęp do cyklu życia.

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

Fragment MapView we fragmencie jest taki sam jak w przykładzie powyżej w przypadku MapView w aktywności, z tym wyjątkiem, że fragment ten zapełnia układ, który zawiera metodę MapView we fragmencie onCreateView().

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

Dostosowanie powiększenia kamery w celu skoncentrowania się na podróży

Domyślny przycisk Moja lokalizacja wbudowany w pakiet SDK SDK Map Google wyśrodkowuje aparat na lokalizacji urządzenia.

Jeśli jest aktywna sesja udostępniania podróży, możesz ustawić kamerę tak, aby koncentrowała się na podróży, a nie na lokalizacji urządzenia.

Wbudowany pakiet SDK dla użytkowników Androida: AutoKamera

Aby ułatwić Ci koncentrację na podróży, a nie na lokalizacji urządzenia, pakiet SDK dla klientów indywidualnych udostępnia funkcję automatycznej kamery, która jest domyślnie włączona. Kamera powiększy obraz, aby skupić się na trasie udostępniania i następnej trasie.

Dostosowywanie działania kamery

Jeśli chcesz mieć większą kontrolę nad działaniem kamery, możesz wyłączyć lub włączyć aparat automatyczny za pomocą funkcji consumerController.setAutocameraEnabled().

consumerController.getKameraUpdate() zwraca w danym momencie zalecane granice aparatu. Możesz podać ten argument CameraUpdate jako argument GoogleMap.movecamera() lub GoogleMap.animatecamera().

Korzystaj z map i wspólnych przejazdów

Aby korzystać ze wspólnych przejazdów i interakcji z mapą w aplikacji, musisz mieć dostęp do ConsumerGoogleMap i ConsumerController. ConsumerMapFragment i ConsumerMapView zarówno asynchronicznie zwracają ConsumerGoogleMap, jak i ConsumerMapReadyCallback. ConsumerGoogleMap zwraca ConsumerController z: getConsumerController(). Dostęp do ConsumerGoogleMap i ConsumerController możesz uzyskać poniżej.

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

Mapa konsumentów

ConsumerGoogleMap to kod towarzyszący klasy GoogleMap. Daje ona Twojej aplikacji możliwość interakcji z mapą przy użyciu interfejsu API odpowiadającego interfejsowi GoogleMap. Korzystanie z mapy konsumenta umożliwia bezproblemową współpracę aplikacji i przejazdów z tą samą bazą GoogleMap. Na przykład GoogleMap zezwala na rejestrację tylko jednego wywołania zwrotnego, a ConsumerGoogleMap obsługuje podwójne zarejestrowane wywołania zwrotne. Dzięki nim wywołania aplikacji i wspólne przejazdy mogą rejestrować wywołania zwrotne, które są wywoływane kolejno.

Kontroler konsumenta

ConsumerController umożliwia dostęp do funkcji wspólnych przejazdów, takich jak monitorowanie podróży, kontrolowanie stanu podróży i ustawianie lokalizacji.

Konfigurowanie udostępniania ścieżki

Gdy backend zmieni się na zgodny z konsumentem pojazdem, możesz uruchomić interfejs użytkownika udostępniania podróży za pomocą JourneySharingSession. Współdzielenie przejazdu pokazuje dopasowaną lokalizację pojazdu i trasę. Po wdrożeniu pakietu SDK w aplikacji możesz dodać funkcję monitorowania podróży, nasłuchiwania aktualizacji i obsługi błędów. W poniższych procedurach przyjęto, że usługi backendu są wdrożone, a usługi związane z dopasowywaniem konsumentów do pojazdów działają.

1. Zarejestruj detektor na obiekcie TripModel, aby uzyskać szczegółowe informacje o podróży, takie jak szacowany czas przyjazdu i odległość, jaką musi pokonać pojazd.

   Java

   // Create a TripModel instance for listening to updates to the trip specified by this trip name.
   String tripName = ...;
   TripModelManager tripModelManager = consumerApi.getTripModelManager();
   TripModel tripModel = tripModelManager.getTripModel(tripName);
   
   // Create a JourneySharingSession instance based on the TripModel.
   JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
   
   // Add the JourneySharingSession instance on the map for updating the UI.
   consumerController.showSession(session);
   
   // Register for trip update events.
   tripModel.registerTripCallback(new TripModelCallback() {
     @Override
     public void onTripETAToNextWaypointUpdated(
         TripInfo tripInfo, @Nullable Long timestampMillis) {
       // ...
     }
   
     @Override
     public void onTripActiveRouteRemainingDistanceUpdated(
         TripInfo tripInfo, @Nullable Integer distanceMeters) {
       // ...
     }
   
     // ...
   });
   

   Kotlin

   // Create a TripModel instance for listening to updates to the trip specified by this trip name.
   val tripName = "tripName"
   val tripModelManager = consumerApi.getTripModelManager()
   val tripModel = tripModelManager.getTripModel(tripName)
   
   // Create a JourneySharingSession instance based on the TripModel.
   val session = JourneySharingSession.createInstance(tripModel)
   
   // Add the JourneySharingSession instance on the map for updating the UI.
   consumerController.showSession(session)
   
   // Register for trip update events.
   tripModel.registerTripCallback(
     object : TripModelCallback() {
       override fun onTripETAToNextWaypointUpdated(
         tripInfo: TripInfo,
         timestampMillis: Long?,
       ) {
         // ...
       }
   
       override fun onTripActiveRouteRemainingDistanceUpdated(
         tripInfo: TripInfo,
         distanceMeters: Int?,
       ) {
         // ...
       }
   
     // ...
   })
   

2. Skonfiguruj podróż za pomocą TripModelOptions.

   Java

   // Set refresh interval to 2 seconds.
   TripModelOptions tripOptions =
       TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
   tripModel.setTripModelOptions(tripOptions);
   

   Kotlin

   // Set refresh interval to 2 seconds.
   val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
   tripModel.setTripModelOptions(tripOptions)
   

Przestań udostępniać podróż

Pamiętaj, aby zatrzymać udostępnianie ścieżki, gdy nie jest już potrzebna, na przykład gdy aktywność hosta została zniszczona. Zatrzymanie udostępniania ścieżki powoduje też zatrzymanie żądań sieciowych do Fleet Engine i zapobiega wyciekom pamięci.

Poniższy przykładowy kod pokazuje, jak zatrzymać udostępnianie ścieżki.

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

Obsługa błędów podróży

Metoda onTripRefreshError wyświetla błędy, które pojawiają się podczas monitorowania podróży. Błędy związane z pakietem SDK dla klientów indywidualnych są zgodne z tymi samymi wskazówkami HTTP/RPC ustanowionymi dla Google Cloud Platform. Do częstych błędów wyświetlanych podczas monitorowania podróży należą:

Więcej informacji znajdziesz w artykule Obsługa błędów konsumenckich dotyczących pakietu SDK.