A solução de viagens e entregas sob demanda está disponível apenas para parceiros selecionados.

Esta página foi traduzida pela API Cloud Translation.

Primeiros passos com o SDK do consumidor para Android

É possível usar o SDK para consumidor para criar e executar um app de consumidor básico integrado aos serviços de back-end de viagens e entregas sob demanda. É possível criar um app Trip and Order Progress para mostrar uma viagem ativa, responder a atualizações e processar erros relacionados.

Como o SDK do consumidor tem uma arquitetura modular, é possível usar as partes da API que você quer usar no seu app e integrá-las às suas próprias APIs, aos serviços de back-end fornecidos pelo Fleet Engine e às APIs adicionais 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 mais recentes do SDK para consumidor estão disponíveis usando o repositório Maven do Google. O canal de repositório privado usado anteriormente foi descontinuado.

Gradle

Adicione a instrução a seguir ao seu arquivo build.gradle:

repositories {
    ...
    google()
}

Maven

Adicione a instrução a seguir ao seu arquivo pom.xml:

<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 ser direcionado ao minSdkVersion 23 ou mais recente.

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

Configurar seu projeto de desenvolvimento

Para configurar seu projeto de desenvolvimento e gerar uma chave de API para ele no Console do Google Cloud:

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é que o novo projeto esteja visível no console do Google Cloud.
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 > Biblioteca, pesquise e ative o SDK do Maps para Android.
Para gerar uma chave de API para o projeto, selecione APIs e serviços > Credenciais > Criar credenciais > Chave de API. Para mais informações sobre como conseguir uma chave de API, consulte Gerar 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. O repositório inclui os arquivos .pom (Project Object Model) do SDK e Javadocs. Para adicionar o SDK do consumidor ao seu app:

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

Se você tiver uma configuração de gerenciamento de dependências centralizada declarada em settings.gradle, desative-a da seguinte maneira.
- 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()
    }
}
```

Adicione a seguinte dependência à sua configuração do Gradle ou Maven, substituindo o marcador VERSION_NUMBER pela 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>

O SDK do consumidor depende do SDK do Maps. Essa dependência é configurada de forma que, se a versão do SDK do Maps não estiver explicitamente definida no arquivo de configuração do build, como mostrado abaixo, quando uma nova versão do SDK do Maps for lançada, o SDK Consumer vai continuar usando a versão mínima 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, adicione a chave de API a ele. Use a chave de API do projeto que você recebeu durante a configuração do projeto de desenvolvimento.

Esta seção descreve como armazenar sua chave de API para que ela possa ser referenciada com mais segurança pelo seu app. Não faça a verificação dela no seu sistema de controle de versões. Ele precisa ser armazenado no arquivo local.properties, que está localizado no diretório raiz do projeto. Para saber mais sobre o arquivo 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:

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

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

Groovy

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

Kotlin

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

Se você usa o Android Studio, sincronize seu projeto com o Gradle.
Abra o local.properties no diretório do nível do projeto e adicione o seguinte código. Substitua YOUR_API_KEY pela sua chave de API.
```
MAPS_API_KEY=YOUR_API_KEY
```
No seu arquivo AndroidManifest.xml, acesse com.google.android.geo.API_KEY e atualize o atributo android:value da seguinte maneira:
```
<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 da seção de avisos legais do app. É melhor incluir as atribuições como um item de menu independente ou como parte de um item de menu Sobre.

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

Consulte https://developers.google.com/android/guides/opensource para saber 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 uma ou mais declarações em um serviço. Por exemplo, um servidor pode gerar um token com a declaração "conectado como administrador" e fornecê-la a um cliente. O cliente pode usar esse token para provar que está conectado como administrador.

O SDK do 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 precisa incluir uma declaração tripid:TRIP_ID no cabeçalho authorization do token, em que TRIP_ID é o ID da viagem. Isso dá ao SDK do consumidor acesso 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.

Recomendamos que sua implementação de callback armazene os tokens de autorização em cache e os atualize somente quando o tempo expiry tiver passado. Os tokens devem ter 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 o tripId necessário para o contexto.

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

Java

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

Kotlin

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 os serviços apropriados e o SDK do consumidor.

Acesse a instância `ConsumerApi`

Para usar o SDK do consumidor, seu app precisa inicializar 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 o Guia do usuário do Fleet Engine para mais informações sobre como criar o projeto.

Seu app precisa implementar o AuthTokenFactory, conforme descrito em Autenticação do SDK do consumidor.

Java

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

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

Kotlin

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 abaixo resume o renderizador padrão por versão do SDK do Maps e a compatibilidade dos dois. Recomendamos o uso do renderizador mais recente. No entanto, se você precisar usar o renderizador legado, poderá especificá-lo explicitamente usando MapsInitializer.initialize().

Versão do SDK do Maps	Compatível com o renderizador mais recente	Compatível com o renderizador legado	Renderizador padrão
V18.1.0 e anteriores	Sim	Sim	Legado*
V18.2.0	Sim	Sim	Mais recentes

* 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

Gradle

Adicione o seguinte ao seu build.gradle:

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

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>

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

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

java

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

Kotlin

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

Use ConsumerMapFragment ou ConsumerMapView para criar a interface do usuário do aplicativo. ConsumerMapFragment permite que você defina o mapa usando um Fragment, enquanto ConsumerMapView permite usar um View. A funcionalidade de compartilhamento de viagem é a mesma no ConsumerMapView e no ConsumerMapFragment. Portanto, você pode escolher uma com base na melhor opção para seu aplicativo: View ou Fragment.

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

Se o design do seu app exigir suporte a dispositivos com API 19 (KitKat) e drawables vetoriais, adicione o código abaixo à sua atividade. Esse código estende AppCompatActivity para usar os drawables vetoriais no SDK do consumidor.

Java

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

// ...

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

Kotlin

// ...
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 app (localizado em /res/layout). O fragmento (ou visualização) fornece acesso ao mapa de compartilhamento de jornada, que pode ser acessado e modificado pelo seu app. O mapa também fornece um identificador para o ConsumerController, o que permite que o app controle e personalize a experiência de compartilhamento da jornada.

Mapa e controle da jornada de compartilhamento

Defina o mapa de compartilhamento da jornada como um fragmento (usando ConsumerMapFragment) ou como uma visualização (usando ConsumerMapView), conforme mostrado no exemplo de código a seguir. Seu método onCreate() precisa chamar getConsumerGoogleMapAsync(callback), que retorna o ConsumerGoogleMap de forma assíncrona no callback. Em seguida, use a ConsumerGoogleMap para exibir o compartilhamento de jornada, que poderá ser atualizado pelo app conforme necessário.

ConsumerMapFragment

Defina o fragmento no arquivo XML de layout do aplicativo, conforme demonstrado no 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 método onCreate().

Java

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

}

Kotlin

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(). Além do parâmetro de callback, ele exige a atividade ou o fragmento que o contém e o GoogleMapOptions (que pode ser nulo), contendo atributos de configuração para o MapView. A atividade ou a classe base de fragmento precisa ser uma FragmentActivity ou um Fragment de suporte (respectivamente), já que fornecem acesso ao ciclo de vida.

Java

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

}

Kotlin

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

Uma MapView em um fragmento é igual ao exemplo acima para MapView em uma atividade, exceto pelo fato de que o fragmento infla o layout que inclui o MapView no método onCreateView() do fragmento.

Java

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

}

Kotlin

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 para 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 SDK do consumidor fornece um recurso AutoCamera que é ativado por padrão. A câmera aumenta o zoom para focar na rota de compartilhamento da jornada e no próximo waypoint da viagem.

AutoCamera

Como personalizar o comportamento da câmera

Se você precisa de mais controle do comportamento da câmera, pode desativar ou ativar a 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 seu app, você precisa de acesso a ConsumerGoogleMap e ConsumerController. ConsumerMapFragment e ConsumerMapView retornam ConsumerGoogleMap de forma assíncrona em ConsumerMapReadyCallback. ConsumerGoogleMap retorna ConsumerController de getConsumerController(). É possível acessar ConsumerGoogleMap e ConsumerController desta maneira.

Java

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

Kotlin

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 de wrapper para a classe GoogleMap. Ela permite que o app interaja com o mapa usando uma API equivalente à GoogleMap. Com o mapa do consumidor, seu app e o serviço de transporte por aplicativo interagem perfeitamente com o mesmo GoogleMap. Por exemplo, GoogleMap permite apenas um único registro de callback, mas ConsumerGoogleMap oferece suporte a callbacks com registros duplos. Esses callbacks permitem que o app e o transporte por aplicativo registrem callbacks chamados em sequência.

ConsumerController

O ConsumerController oferece acesso a funcionalidades de compartilhamento de viagens, como monitorar, controlar o status 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 de compartilhamento da jornada. Esse recurso mostra a localização e o trajeto do veículo correspondente. Depois de implementar o SDK no app, você pode adicionar a funcionalidade para monitorar viagens, detectar atualizações e processar erros. Os procedimentos a seguir pressupõem que os serviços de back-end estejam em vigor e que seus serviços para corresponder consumidores a veículos estejam operacionais.

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 percorrer 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?,
    ) {
      // ...
    }

  // ...
})

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.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

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

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

Kotlin

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 de erros do SDK para consumidores segue as mesmas diretrizes HTTP/RPC estabelecidas para o Google Cloud Platform. Confira alguns erros comuns durante o monitoramento de viagens:

HTTP	RPC	Descrição
400	INVALID_ARGUMENT	O cliente especificou um nome de viagem inválido. O nome da viagem precisa seguir o formato `providers/{provider_id}/trips/{trip_id}`. O provider_id precisa ser o ID do projeto do Cloud de propriedade do provedor de serviços.
401	UNAUTHENTICATED	Solicitação não autenticada devido a um token JWT inválido. Esse erro ocorrerá se o token JWT for assinado sem um ID de viagem ou se o token JWT tiver expirado.
403	PERMISSION_DENIED	O cliente não tem permissão suficiente. Esse erro ocorrerá se o token JWT for inválido, o cliente não tiver permissão ou a API não estiver ativada para o projeto do cliente. O token JWT pode estar ausente ou ele está assinado com um ID de viagem que não corresponde ao ID de viagem solicitado.
429	RESOURCE_EXHAUSTED	A cota de recursos está em zero ou a taxa de tráfego excede o limite.
503	UNAVAILABLE	Serviço indisponível. Normalmente, o servidor está inativo.
504	DEADLINE_EXCEEDED	O prazo de solicitação foi excedido. Isso acontecerá somente se o autor da chamada definir um prazo menor que o prazo padrão do método (ou seja, se o prazo solicitado não for suficiente para o servidor processar a solicitação) e a solicitação não for concluída dentro do prazo.

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

Primeiros passos com o SDK do consumidor para Android

Requisitos mínimos do sistema

Configuração do build e das dependências

Gradle

Maven

Configuração do projeto

Configurar seu projeto de desenvolvimento

Adicionar o SDK do consumidor ao seu app

Gradle

Maven

Gradle

Maven

Adicionar a chave de API ao seu app

Groovy

Kotlin

Groovy

Kotlin

Incluir as atribuições necessárias no app

Autenticação do SDK do consumidor

Callbacks de JSON Web Token

Java

Kotlin

Inicializar a API

Acesse a instância ConsumerApi

Java

Kotlin

SDK do Maps e renderizadores de mapas

Adicionar o SDK do Maps como uma dependência

Gradle

Maven

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

java

Kotlin

Criar a interface do usuário

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

Java

Kotlin

Adicionar a visualização ou o fragmento do mapa

Mapa e controle da jornada de compartilhamento

ConsumerMapFragment

Java

Kotlin

ConsumerMapView

Java

Kotlin

Java

Kotlin

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

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

Como personalizar o comportamento da câmera

Acesse serviços de transporte por aplicativo e mapas

Java

Kotlin

ConsumerGoogleMap

ConsumerController

Configurar o compartilhamento da jornada

Java

Kotlin

Java

Kotlin

Parar compartilhamento da viagem

Java

Kotlin

Gerenciar erros de viagem

Acesse a instância `ConsumerApi`