Criar uma viagem e receber um token de viagem

Para iniciar uma sessão de navegação guiada com segurança para um motorista, seu back-end precisa criar uma viagem e receber um token de viagem autenticado da API Navigation Connect.

No Navigation Connect, uma viagem representa uma sessão de navegação para um único destino. Para criar uma viagem e receber o token de viagem autenticado (authToken) necessário para autorizar a sessão, envie uma mensagem CreateTripRequest ao método CreateTrip. Transmita o token de viagem ao seu app para dispositivos móveis para incluí-lo no URL de inicialização do Google Maps ou do Waze.

Neste guia, descrevemos como concluir esse processo gerando um ID de viagem exclusivo e enviando sua solicitação de API.

Criar uma mensagem CreateTripRequest

Para criar uma viagem e receber um token de viagem, siga estas etapas para criar e enviar uma mensagem CreateTripRequest:

  1. Autenticar: use o Application Default Credentials (ADC) para receber um token de acesso e autorizar sua solicitação. Para mais detalhes, consulte Criar um token OAuth.
  2. Gerar um ID de viagem: crie um ID de viagem exclusivo (tripId) no formato UUIDv4 para identificar a viagem no seu servidor.
  3. Crie o payload: crie um payload JSON que inclua os IDs do app e as definições de configuração.
  4. Chame o método CreateTrip: envie uma solicitação POST para a API com o token de acesso no cabeçalho e o payload no corpo.

O exemplo a seguir mostra como criar uma viagem enviando uma mensagem CreateTripRequest:

#!/bin/bash

# Authenticate with ADC
access_token="$(gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL)"

# Generate a unique Trip ID
trip_id="$(uuidgen)"

# Construct the payload
payload=$(cat <<EOF
{
  "androidAppId": "ANDROID_APP_ID",
  "iosAppId": "IOS_APP_ID",
  "config": {
    "enablePubsub": true
  }
}
EOF
)

# Call the CreateTrip method to request a trip token
curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
-H "Authorization: Bearer ${access_token}" \
-H "Content-Type: application/json" \
-d "${payload}"

Configurações opcionais

Para personalizar os dados da viagem, ajuste as seguintes configurações na mensagem CreateTripRequest:

Recurso Tipo Descrição
Relatório de rota restante boolean

Para receber a polilinha do trajeto ativo e as condições de trânsito em tempo real, defina config.enableRemainingRouteReporting como true.

Os motoristas precisam da versão 5.20.0.2 ou mais recente do Waze no Android, 5.20.0.1 ou mais recente no iOS ou da versão 26.27 ou mais recente do Google Maps para Android.

Relatório de desvio de rota (somente Waze) boolean

Para monitorar quando um motorista sai do trajeto, defina config.enableRouteDeviationReporting como true.

Os motoristas precisam da versão 5.22 ou mais recente do Waze.

Frequência de atualização de viagens boolean

Por padrão, o Navigation Connect atualiza os dados da viagem a cada 60 segundos. Para ativar as atualizações de alta frequência (a cada 5 segundos), defina config.enableHighFrequencyUpdates como true.

Geração de eventos do Google Cloud Pub/Sub boolean

Para ativar a geração de eventos de viagem usando o Google Cloud Pub/Sub, defina config.enablePubsub como true. Esse recurso fica desativado por padrão.

Máscara de campo do Google Cloud Pub/Sub FieldMask

Para gerenciar os tamanhos de payload e reduzir a carga de processamento de back-end ou os custos de uso do Google Cloud Pub/Sub, use config.pubsubFieldMask para excluir campos pesados (como execution.remainingRoute) do fluxo de eventos. Para mais informações sobre o tamanho do payload dos dados de rota restantes, consulte Processar dados de rota restantes.

Receber o token de viagem da resposta

O método CreateTrip retorna uma resposta que contém o token de viagem autenticado. Para autorizar a sessão de navegação, extraia esse token da resposta e transmita-o ao app para dispositivos móveis para inclusão no URL de inicialização.

O exemplo de código a seguir mostra uma resposta de exemplo:

{
    "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z"
}

Essa resposta inclui os seguintes valores:

  • PROJECT_NUMBER: um identificador numérico exclusivo para o projeto. Ele é diferente do ID alfanumérico do projeto, mas representa o mesmo projeto do Google Cloud.
  • TRIP_ID: o ID da viagem gerado pelo back-end no formato UUIDv4.
  • BASE64_ENCODED_TRIP_TOKEN: o token de viagem autenticado (authToken.token) retornado pelo método CreateTrip. Transmita esse token para seu app para dispositivos móveis para iniciar a navegação guiada rastreada no Google Maps ou no Waze.

A seguir

Use o token de viagem para iniciar o Google Maps ou o Waze.

Iniciar o Google Maps ou o Waze