Primeiros passos com o SDK do consumidor para Android

É possível usar o SDK do consumidor para criar e executar um app de consumidor básico integrado com os serviços de back-end da solução de viagens e entregas sob demanda. É possível criar um aplicativo Trip and Order Progress que possa exibir uma viagem ativa; responder a atualizações de viagens e lidar com erros de viagens.

Como o SDK do consumidor tem uma arquitetura modular, você pode usar as partes da API que você quer usar para seu app específico e integrá-los com suas próprias APIs, serviços de back-end fornecidos pelo Fleet Engine, e outras APIs da Plataforma Google Maps.

Requisitos mínimos do sistema

O dispositivo móvel precisa ter o Android 6,0 (nível 23 da API) ou mais recente.

Configuração do build e das dependências

As versões 1.99.0 e posteriores do SDK para consumidor estão disponíveis usando o SDK do repositório de dados. O canal de repositório privado usado anteriormente foi descontinuado.

repositories {
    ...
    google()
}

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

Configuração do projeto

Para usar o SDK do consumidor para Android, seu app precisa segmentar minSdkVersion 23 ou mais recente.

Para executar um app criado com o SDK do consumidor, o Android dispositivo deve ter Google Play Services instalado.

Configurar seu projeto de desenvolvimento

Como configurar seu projeto de desenvolvimento e gerar uma chave de API para o projeto no console do Google Cloud:

1. Crie um novo projeto do console do Google Cloud ou selecione um projeto atual para usar com o SDK do consumidor. Aguarde alguns minutos até o novo projeto fica visível no console do Google Cloud.

2. Para executar o app de demonstração, seu projeto precisa ter acesso ao SDK do Maps. para Android. No console do Google Cloud, selecione APIs e Serviços > Library, pesquise e ative o SDK do Maps para Android

3. Receba uma chave de API para o projeto selecionando APIs e Serviços > Credenciais > Criar credenciais > Chave de API. Para mais informações sobre como acessar uma chave de API, consulte Gere uma chave de API.

Adicionar o SDK do consumidor ao seu app

O SDK do consumidor está disponível em um repositório Maven particular. A inclui os arquivos .pom (Project Object Model) do SDK e Javadocs. Para adicionar o SDK do consumidor ao seu app:

1. Configure seu ambiente para acessar o repositório Maven do host, conforme descrito em na seção anterior.

   Se você tiver uma configuração de gerenciamento de dependências centralizada declarada em settings.gradle, desative-a desta forma.

   • Remova o seguinte bloco de código em settings.gradle:

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

2. Adicione a seguinte dependência à sua configuração do Gradle ou Maven, substituindo " O marcador VERSION_NUMBER para a versão desejada do SDK do consumidor.

   Gradle

   Adicione o seguinte ao seu build.gradle:

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

   Maven

   Adicione o seguinte ao seu pom.xml:

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

3. O SDK do consumidor depende do SDK do Maps. Essa dependência é configurada de modo que, se a versão do SDK do Maps não for explicitamente definida nos o arquivo de configuração do build, como mostrado abaixo, quando uma nova versão do Maps for lançado, o SDK para consumidor vai continuar usando o mínimo compatível do SDK do Maps exigida por ela.

   Gradle

   Adicione o seguinte ao seu build.gradle:

   dependencies {
     ...
     implementation 'com.google.android.gms:play-services-maps:18.1.0'
   }
   

   Maven

   Adicione o seguinte ao seu pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.gms</groupId>
       <artifactId>play-services-maps</artifactId>
       <version>18.1.0</version>
     </dependency>
   </dependencies>
   

Adicionar a chave de API ao seu app

Depois de adicionar o SDK do consumidor ao app, inclua a chave de API nele. Você precisa usar a chave de API do projeto que recebeu ao configure seu projeto de desenvolvimento.

Esta seção descreve como armazenar sua chave de API para que ela seja mais segura referenciadas pelo seu app. Não inclua a chave de API na sua versão de controle de acesso. Ele será armazenado no arquivo local.properties, que é localizado no diretório raiz do seu projeto. Para mais informações sobre o local.properties, consulte Arquivos de propriedades do Gradle.

Para otimizar essa tarefa, use o Plug-in Secrets Gradle para Android (em inglês).

Para instalar o plug-in e armazenar sua chave de API, siga estas instruções:

1. Abra seu arquivo build.gradle no nível raiz e adicione o seguinte código ao Elemento dependencies em buildscript.

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

2. Abra o arquivo build.gradle no nível do app e adicione o seguinte código ao plugins.

   Groovy

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

   Kotlin

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

3. Se você usa o Android Studio, sincronizar seu projeto com o Gradle.

4. Abra o local.properties no diretório do nível do projeto e adicione o código a seguir. Substitua YOUR_API_KEY pela sua chave de API.

   MAPS_API_KEY=YOUR_API_KEY
   

5. No seu arquivo AndroidManifest.xml, acesse com.google.android.geo.API_KEY e atualize o atributo android:value desta forma:

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

O exemplo a seguir mostra um manifesto completo para um app de exemplo:

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

Incluir as atribuições necessárias no app

Se você usa o SDK do consumidor no seu app, é necessário incluir texto de atribuição e licenças de código aberto como parte dos avisos legais do seu app nesta seção. É melhor incluir as atribuições como um item de menu independente ou como no item de menu Sobre.

As informações sobre as licenças podem ser encontradas em "third_party_licenses.txt" arquivo no o arquivo AAR desarquivado.

Consulte https://developers.google.com/android/guides/opensource sobre como incluir avisos de código aberto.

Autenticação do SDK do consumidor

O SDK para consumidor fornece autenticação usando JSON Web Tokens. Um JSON Web Token (JWT) é um token de acesso em base JSON que fornece um ou mais reivindicações em um serviço. Por exemplo, um servidor pode gerar um token com a declaração "conectado como administrador"; e forneça que para um cliente. O cliente poderia então usar esse token para provar que ele fez login como administrador.

O SDK para consumidor usa o JSON Web Token fornecido pelo aplicativo para se comunicar com o Fleet Engine. Consulte Autenticação e autorização do mecanismo de frota para mais informações.

O token de autorização deve incluir uma declaração tripid:TRIP_ID no Cabeçalho authorization, em que TRIP_ID é o ID da viagem. Assim, o consumidor Acesso do SDK aos detalhes da viagem, incluindo posição do veículo, trajeto e HEC.

Callbacks de JSON Web Token

O SDK do consumidor registra um callback de token de autorização com o aplicativo durante a inicialização. O SDK chama o aplicativo para receber um token para todas as solicitações de rede que exigem autorização.

É altamente recomendável que a autorização de cache de implementação de callback e atualize-os somente quando o tempo de expiry tiver passado. Os tokens devem ser emitidos com validade de uma hora.

O callback do token de autorização especifica qual token de serviço é necessário para o serviço TripService. Ele também fornece os tripId necessários para contextualizar.

O exemplo de código a seguir demonstra como implementar uma autorização callback do token.

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

Inicializar a API

Antes de seguir esses procedimentos, presume-se que você ativou o serviços adequados e o SDK do consumidor.

Acesse a instância ConsumerApi

Para usar o SDK do consumidor, seu app precisa ser inicializado ConsumerApi de forma assíncrona. A API é um singleton. O método de inicialização usa um AuthTokenFactory. A fábrica gera novos Tokens JWT para o usuário, quando necessário.

O providerId é o ID do projeto do Google Cloud. Consulte a Guia do usuário do Fleet Engine para mais informações sobre como criar o projeto.

O app precisa implementar o AuthTokenFactory, conforme descrito nas Autenticação do SDK do consumidor.

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
}

SDK do Maps e renderizadores de mapas

O SDK para consumidor v2.x.x é compatível com o SDK do Maps para Android v18.1.0 e mais recentes. A tabela a seguir, resume o renderizador padrão por versão do SDK do Maps e a compatibilidade dos dois renderizadores. No entanto, recomendamos usar o renderizador mais recente se você precisar para usar o renderizador legado, então você poderá especificá-lo explicitamente usando MapsInitializer.initialize()

* Com o lançamento do novo renderizador do Maps, o renderizador Mais recente será o padrão.

Adicionar o SDK do Maps como uma dependência

dependencies {
  //...
  implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}

 <dependencies>
   ...
   <dependency>
     <groupId>com.google.android.gms</groupId>
     <artifactId>play-services-maps</artifactId>
     <version>18.1.0</version>
   </dependency>
 </dependencies>

Inicialize o SDK do Maps antes de inicializar o SDK do consumidor

Na classe Application ou de inicialização Activity, chame MapsInitializer.initialize() e aguardar o resultado da solicitação do renderizador antes de inicializar SDK do consumidor.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);
  initViews();

  MapsInitializer.initialize(getApplicationContext(), Renderer.LATEST,
      new OnMapsSdkInitializedCallback() {
        @Override
        public void onMapsSdkInitialized(Renderer renderer) {
          switch (renderer) {
            case LATEST:
              Log.i("maps_renderer", "LATEST renderer");
              break;
            case LEGACY:
              Log.i("maps_renderer", "LEGACY renderer");
              break;
          }

          initializeConsumerSdk();
        }
      });
}

fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)
  initViews()

  MapsInitializer.initialize(
    getApplicationContext(), Renderer.LATEST,
    object : OnMapsSdkInitializedCallback() {
      fun onMapsSdkInitialized(renderer: Renderer?) {
        when (renderer) {
          LATEST -> Log.i("maps_renderer", "LATEST renderer")
          LEGACY -> Log.i("maps_renderer", "LEGACY renderer")
        }
        initializeConsumerSdk()
      }
    })
  }

Criar a interface do usuário

É possível usar ConsumerMapFragment ou ConsumerMapView para criar a interface do usuário do para o aplicativo. ConsumerMapFragment permite definir seu mapa usando um Fragment, enquanto ConsumerMapView permite que você use uma View. Transporte por aplicativo a funcionalidade é a mesma em ConsumerMapView e ConsumerMapFragment, então é possível escolher um com base se o View ou Fragment é melhor para seu aplicativo.

Foi adicionado suporte à API 19 (KitKat) e aos drawables vetoriais.

Se o design do seu app precisar de suporte para dispositivos com API 19 (KitKat) e drawables vetoriais, adicione o seguinte código à sua atividade. Esse código se estende AppCompatActivity para usar o Drawables vetoriais no SDK do consumidor.

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

// ...

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

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

// ...

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

Adicionar a visualização ou o fragmento do mapa

Você cria o mapa para exibir o compartilhamento da jornada em um fragmento do Android. ou uma visualização, que você define no arquivo XML de layout do aplicativo (localizado em /res/layout). Em seguida, o fragmento (ou visualização) fornece acesso à jornada. mapa de compartilhamento, que seu aplicativo pode acessar e modificar. O mapa também fornece uma o alça até o ConsumerController, que permite que o app controle e personalizar a experiência de compartilhamento de jornadas.

Mapa e controle da jornada de compartilhamento

Você define o mapa de compartilhamento da jornada como um fragmento (usando o ConsumerMapFragment) ou como uma visualização (usando ConsumerMapView), conforme mostrado nas exemplo de código a seguir. Seu método onCreate() precisa chamar getConsumerGoogleMapAsync(callback), que retorna ConsumerGoogleMap. de forma assíncrona no callback. Depois, use ConsumerGoogleMap para mostrar compartilhamento de jornada, e ele pode ser atualizado conforme necessário pelo seu aplicativo.

ConsumerMapFragment

Defina o fragmento no arquivo XML de layout do aplicativo, conforme demonstrado no o exemplo de código a seguir.

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

A chamada para getConsumerGoogleMapAsync() precisa vir do 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()!!
        }
      }
    )
  }
}

ConsumerMapView

A visualização pode ser usada em um fragmento ou uma atividade, conforme definido no Arquivo 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" />

A chamada para getConsumerGoogleMapAsync() precisa ser feita de onCreate(). Em além do parâmetro callback, ela exige a atividade ou o fragmento, e GoogleMapOptions (que pode ser nulo), contendo a configuração para o MapView. A atividade ou a classe base de fragmento precisa ser um FragmentActivity ou um Fragment de suporte (respectivamente), já que eles fornecem acesso ao ciclo de vida dele.

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

Um MapView em um fragmento é o mesmo do exemplo acima para MapView no uma atividade, exceto que o fragmento infla o layout que inclui o MapView no método onCreateView() do fragmento.

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

Ajustando o zoom da câmera para focar em uma viagem

O botão "Meu local" padrão integrado ao SDK do Maps centraliza a câmera no local do dispositivo.

Se houver uma sessão ativa de Compartilhamento de jornada, centralize a câmera focar na jornada em vez do local do dispositivo.

Solução integrada do SDK do consumidor para Android: AutoCamera

Para que você se concentre na jornada em vez do local do dispositivo, o O SDK do consumidor fornece um recurso AutoCamera que é ativada por padrão. A câmera aumenta o zoom para focar na rota de compartilhamento da jornada e o próximo ponto de referência da viagem.

Como personalizar o comportamento da câmera

Para controlar melhor o comportamento da câmera, desative ou ative câmera automática usando ConsumerController.setAutoCameraEnabled().

ConsumerController.getCameraUpdate() retorna os limites recomendados da câmera no momento. Você pode fornecer esse CameraUpdate como um argumento para GoogleMap.moveCamera() ou GoogleMap.animateCamera().

Acesse serviços de transporte por aplicativo e mapas

Para oferecer suporte ao serviço de transporte por aplicativo e à interação com o mapa no app, você precisa ter acesso para ConsumerGoogleMap e ConsumerController. ConsumerMapFragment e ConsumerMapView retornam de forma assíncrona. ConsumerGoogleMap em ConsumerMapReadyCallback. Devolução por ConsumerGoogleMap ConsumerController de getConsumerController(). Você pode acessar ConsumerGoogleMap e ConsumerController da seguinte forma.

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

ConsumerGoogleMap

ConsumerGoogleMap é uma classe wrapper para o GoogleMap. Ela oferece ao app a capacidade de interagem com o mapa usando uma API equivalente à GoogleMap: Com o mapa do consumidor, seu app e o transporte compartilhar para interagir perfeitamente com o mesmo GoogleMap subjacente. Por exemplo: GoogleMap permite apenas um único registro de callback, mas ConsumerGoogleMap oferece suporte a callbacks registrados duplos. Esses callbacks permitem que o app e o transporte por aplicativo registrem callbacks que são: chamados em sequência.

ConsumerController

O ConsumerController fornece acesso à funcionalidade de transporte por aplicativo, como como monitorar viagens, controlar o status de viagens e definir locais.

Configurar o compartilhamento da jornada

Depois que o back-end corresponder um consumidor a um veículo, use JourneySharingSession. para iniciar a interface do usuário do compartilhamento da jornada. O compartilhamento da jornada mostra os resultados a localização e o trajeto do veículo. Depois de implementar o SDK em seu aplicativo, você pode adicionar a funcionalidade de monitorar viagens, detectar atualizações e lidar com erros. Os procedimentos a seguir pressupõem que os serviços de back-end estão no local e que sua serviços para corresponder consumidores a veículos está operacional.

1. Registre um listener em um objeto TripModel para ver detalhes sobre a viagem, como o HEC (horário estimado de chegada) e a distância que o veículo precisa viajar antes da chegada.

   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. Configure sua viagem usando 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)
   

Parar compartilhamento da viagem

Interrompa o compartilhamento da jornada quando ele não for mais necessário, como quando a atividade do host for destruída. Ao interromper o compartilhamento de viagens, você também interrompe as solicitações de rede ao Fleet Engine e evita vazamentos de memória.

O exemplo de código a seguir demonstra como interromper o compartilhamento da jornada.

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

Gerenciar erros de viagem

O método onTripRefreshError mostra erros que ocorrem durante o monitoramento de viagens. O mapeamento para o SDK do consumidor os erros seguem as mesmas diretrizes HTTP/RPC estabelecidas para Google Cloud Platform Confira alguns erros comuns durante o monitoramento de viagens:

Para mais informações, consulte Tratamento de erros do SDK do consumidor.