Detectar eventos de navegação

Seu app pode detectar eventos que ocorrem enquanto o usuário navega por um trajeto.

Visão geral

Use as seguintes interfaces para detectar eventos de navegação:

Achou o código?

Detectar a chegada a um destino

Aqui, um destino se refere a um destino final ou um waypoint. Para detectar a chegada, chame Navigator.addArrivalListener(), que registra um callback quando o dispositivo chega a um destino.

Ao chegar, o SDK Navigation para Android aciona o callback onArrival(), que pode ser usado para interromper a orientação trecho a trecho usando Navigator.stopGuidance() ou avançar para o próximo ponto de parada usando Navigator.continueToNextDestination(). Se a sessão de navegação incluir apenas um destino ou se não houver mais destinos na lista, chamar Navigator.continueToNextDestination() interrompe automaticamente a orientação.

Quando você chama continueToNextDestination(), o navegador descarta todas as informações sobre o destino anterior. Se você quiser analisar informações sobre o segmento de rota anterior, recupere as informações do navegador antes de chamar continueToNextDestination().

Para evitar vazamentos de memória, chame removeArrivalListener(listener) quando não precisar mais do listener.

mNavigator.addArrivalListener(new Navigator.ArrivalListener() {
    @Override
    public void onArrival(ArrivalEvent arrivalEvent) {
        displayMessage("onArrival: You've arrived at a waypoint: "
                +   mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_BOTH);
        // Start turn-by-turn guidance for the next leg of the route.
        if (arrivalEvent.isFinalDestination()) {
            displayMessage("onArrival: You've arrived at the final destination.",
                    DISPLAY_BOTH);
        } else {
            mNavigator.continueToNextDestination();
            mNavigator.startGuidance();
        }
    }
});

Receber atualizações de localização

Receba um RoadSnappedLocationProvider do NavigationApi e chame RoadSnappedLocationProvider.addLocationListener() para registrar um callback quando a localização ou o rumo do dispositivo mudar. Esse local é ajustado a uma via, então pode ser diferente do local retornado pelo provedor de localização combinada nas APIs Location do Google Play Services.

O SDK Navigation fornece atualizações de local com a maior frequência possível. Quando uma atualização de local está disponível, o SDK Navigation dispara o callback onLocationChanged().

As atualizações de localização ajustadas à via são independentes da navegação e podem continuar mesmo depois que ela é interrompida. A inscrição em atualizações de localização pode causar consumo da bateria, um vazamento de memória ou coleta não intencional de dados de localização do dispositivo se você deixar as atualizações de localização em execução em segundo plano. Chame RoadSnappedLocationProvider.removeLocationListener quando não precisar mais do listener.

mRoadSnappedLocationProvider =
        NavigationApi.getRoadSnappedLocationProvider(getApplication());
if (mRoadSnappedLocationProvider != null) {
    mRoadSnappedLocationProvider.addLocationListener(
            new RoadSnappedLocationProvider.LocationListener() {
                @Override
                public void onLocationChanged(Location location) {
                    displayMessage("onLocationUpdated: Navigation engine has provided a new"
                                    +   " road-snapped location: "
                                    +   location.toString(),
                            DISPLAY_LOG);
                }
            });
} else {
    displayMessage("ERROR: Failed to get a location provider", DISPLAY_LOG);
}

Receber atualizações de tempo e distância

Chame Navigator.addRemainingTimeOrDistanceChangedListener() para registrar um callback quando o tempo restante (segundos) ou a distância (metros) mudar mais do que um determinado limite.

Quando a mudança no tempo ou na distância excede o valor especificado, o SDK Navigation aciona o callback onRemainingTimeOrDistanceChanged().

Para saber o tempo e a distância restantes, chame Navigator.getTimeAndDistanceList(). Os tempos e as distâncias na lista são cumulativos: eles mostram o tempo e a distância do local atual até cada ponto de referência, não de um ponto de referência para outro. O objeto TimeAndDistance agora também retorna delaySeverity. Esse enum será "heavy", "medium", "light" ou "unknown". Isso corresponde à cor que você vê na estimativa de chegada na interface dos mapas (intenso = vermelho, médio = amarelo, leve = verde). Isso é útil se você precisar criar seu próprio rodapé de ETA.

Para evitar vazamentos de memória, chame Navigator.removeRemainingTimeOrDistanceChangedListener(listener) quando o listener não for mais necessário.

O exemplo abaixo solicita um callback se o tempo restante mudar em mais de 60 segundos ou se a distância restante mudar em mais de 100 metros.

mNavigator.addRemainingTimeOrDistanceChangedListener(60, 100,
        new Navigator.RemainingTimeOrDistanceChangedListener() {
            @Override
            public void onRemainingTimeOrDistanceChanged() {
                displayMessage("onRemainingTimeOrDistanceChanged: Time or distance estimate"
                        +   " has changed.",
                        DISPLAY_LOG);
            }
        });

Você pode mostrar as informações de tempo e distância restantes usando a tela integrada com o método setEtaCardEnabled() e transmitindo um parâmetro com o valor TRUE. Para suprimir a exibição de tempo e distância, defina esse valor como FALSE.

Também é possível expor a ETA para vários waypoints usando o método getTimeAndDistanceList().

Receber atualizações de trajeto

Chame Navigator.addRouteChangedListener() para registrar um callback quando a rota mudar.

Quando a rota muda, o SDK Navigation dispara o callback onRouteChanged(). Você pode chamar Navigator.getRouteSegments e Navigator.getCurrentRouteSegment() para encontrar o novo trajeto.

Para evitar vazamentos de memória, chame removeRouteChangedListener(listener) quando não precisar mais do listener.

mNavigator.addRouteChangedListener(new Navigator.RouteChangedListener() {
    @Override
    public void onRouteChanged() {
        displayMessage("onRouteChanged: The driver's route has changed. Current waypoint: "
                +   mNavigator.getCurrentRouteSegment().getDestinationWaypoint().getTitle(),
                DISPLAY_LOG);
    }
});

Detectar quando o modo noturno muda

Chame NavigationView.addOnNightModeChangedListener ou SupportNavigationFragment.addOnNightModeChangedListener para registrar um callback quando o modo noturno mudar.

O exemplo a seguir mostra como detectar mudanças no modo noturno em um fragmento de navegação.

mNavFragment.addOnNightModeChangedListener(new NavigationView.OnNightModeChangedListener() {
    @Override
    public void onNightModeChanged(NightModeChangedEvent nightModeChangedEvent) {
        displayMessage("Night mode is active: " + nightModeChangedEvent.inNightMode(),
        DISPLAY_LOG);
    }
});

Também é possível definir o modo noturno de forma programática. Para mais informações, consulte Ativar o modo noturno.