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

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

Na chegada, o SDK do Navigation para Android aciona o callback onArrival(), que pode ser usado para interromper a navegação guiada usando Navigator.stopGuidance() ou avançar para o próximo ponto de passagem 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() interromperá 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 trecho anterior do trajeto, recupere-as 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

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

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

As atualizações de local ajustadas à via são independentes da navegação e podem continuar mesmo depois que a navegação é interrompida. A inscrição em atualizações do local pode causar o consumo elevado da bateria, um vazamento de memória ou a coleta não intencional de dados de local do dispositivo se você deixar as atualizações do local 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 (segundos) ou a distância (metros) restante mudar além de um determinado limite.

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

Para encontrar 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 passagem, não de um ponto de passagem para outro. O objeto TimeAndDistance também retorna delaySeverity. Esse tipo enumerado é HEAVY, MEDIUM, LIGHT ou UNKNOWN. Isso corresponde à cor que você vê para o HEC na interface do Maps (pesado = 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 não precisar mais do listener.

O exemplo a seguir 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);
            }
        });

É possível mostrar informações sobre o tempo e a 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 o HEC para vários waypoints usando o método getTimeAndDistanceList().

Receber atualizações de trajeto

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

Quando o trajeto muda, o SDK do Navigation aciona o callback onRouteChanged(). Chame 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 NavigationFragment.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 Definir o modo noturno.