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 até 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 para o método CreateTrip. Transmita o token de viagem para seu app para dispositivos móveis e inclua no URL de inicialização do Google Maps ou do Waze.

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

Construir uma mensagem CreateTripRequest

Para criar uma viagem e receber um token, siga estas etapas para construir 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. Construa o payload: crie um payload JSON que inclua seus IDs de app e configuraçõ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
Outros tipos de alertas de trânsito (somente no Waze) boolean

Para receber a polilinha da rota ativa e as condições de trânsito em tempo real, defina config.enableRemainingRouteReporting como true.
Relatórios de desvio de rota (somente no Waze) boolean

Para rastrear quando um motorista sai da rota, defina config.enableRouteDeviationReporting como true.
Frequência de atualização da viagem boolean

Por padrão, o Navigation Connect atualiza os dados da viagem a cada 60 segundos. Para ativar 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 tamanhos de payload e reduzir a carga de processamento do 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 da carga útil dos dados restantes de rotas, consulte Processar os dados restantes de rotas.

Extrair o token da 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 incluir 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 seu 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 seu 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 e inicie a navegação guiada rastreada no Google Maps ou no Waze.

A seguir

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

Abra o Google Maps ou o Waze.