NavigationApi

public final class NavigationApi extends Object

Entry point to the Navigation API. Use the static methods on this class to obtain a reference to the Navigator.

Nested Class Summary

@interface NavigationApi.ErrorCode An ErrorCode is a status code returned by NavigationApi.getNavigator(Activity, NavigatorListener) and NavigationApi.getNavigator(Application, NavigatorListener) when a Navigator could not be successfully obtained. 
interface NavigationApi.NavigatorListener Register a NavigatorListener with NavigationApi.getNavigator(Activity, NavigatorListener) to be notified about the status of said Navigator
interface NavigationApi.OnTermsResponseListener Register an OnTermsResponseListener with NavigationApi.showTermsAndConditionsDialog(Activity, String, OnTermsResponseListener) to be notified when the user accepts or declines the terms and conditions. 

Public Method Summary

static boolean
areTermsAccepted(Application application)
Returns true if the user has previously accepted Google's Navigation terms and conditions.
synchronized static void
clearForegroundServiceManager()
Clears the ForegroundServiceManager and resets the default message and clears the resume intent.
synchronized static ForegroundServiceManager
getForegroundServiceManager(Application application)
Obtains the singleton ForegroundServiceManager instance.
static String
getNavSDKVersion()
Returns the current NavSDK version.
static void
getNavigator(Application application, NavigationApi.NavigatorListener callback)
Obtains the Navigator instance.
static void
getNavigator(Activity activity, NavigationApi.NavigatorListener callback, TermsAndConditionsCheckOption termsCheck)
Obtains the Navigator instance.
static void
getNavigator(Activity activity, NavigationApi.NavigatorListener callback)
Equivalent to getNavigator(activity, callback, termsCheck) in which termsCheck is TermsAndConditionsCheckOption.ENABLED.
static void
getNavigatorNoToS(Application application, NavigationApi.NavigatorListener callback)
Obtains the Navigator instance.
static RoadSnappedLocationProvider
getRoadSnappedLocationProvider(Application application)
Obtains an instance of the RoadSnappedLocationProvider, which can be used to subscribe to road-snapped user locations.
static NavigationTransactionRecorder
getTransactionRecorder(Application application)
Obtains an instance of the NavigationTransactionRecorder, which can be used to record transactions related to navigation.
synchronized static void
initForegroundServiceManagerMessageAndIntent(Application application, Integer notificationId, String defaultMessage, Intent resumeIntent)
Initializes the ForegroundServiceManager instance with arguments for setting the default message and resume intent.
synchronized static void
initForegroundServiceManagerProvider(Application application, Integer notificationId, NotificationContentProvider provider)
Initializes the ForegroundServiceManager instance with a provider that specifies notification content.
static void
resetTermsAccepted(Application application)
Reset the terms and conditions - for testing.
static void
setAbnormalTerminationReportingEnabled(boolean enabled)
Enables/disables reporting abnormal SDK terminations such as the app crashes while the SDK is still running.
static void
showTermsAndConditionsDialog(Activity activity, String companyName, String title, NavigationApi.OnTermsResponseListener listener)
Displays a dialog that directs the user to accept Google's Navigation terms and conditions, using the default look and feel.
static void
showTermsAndConditionsDialog(Activity activity, String companyName, String title, TermsAndConditionsUIParams uiParams, NavigationApi.OnTermsResponseListener listener, TermsAndConditionsCheckOption termsAndConditionsCheckOption)
Displays a dialog that directs the user to accept Google's Navigation terms and conditions.
static void
showTermsAndConditionsDialog(Activity activity, String companyName, NavigationApi.OnTermsResponseListener listener)
Displays a dialog that directs the user to accept Google's Navigation terms and conditions, using the default title and the default look and feel.

Inherited Method Summary

Public Methods

public static boolean areTermsAccepted (Application application)

Returns true if the user has previously accepted Google's Navigation terms and conditions.

You can use this to check whether you should display the terms screen earlier in the application, rather than when the user is about to navigate somewhere. For example, it might be appropriate to check this value when your app is showing other terms and conditions, so that the user can accept all required terms and conditions for the app in one task.

Parameters
application the current application
Returns
  • true if the terms have been accepted by the user, and false otherwise

public static synchronized void clearForegroundServiceManager ()

Clears the ForegroundServiceManager and resets the default message and clears the resume intent. You should be careful to ensure that there are no remaining references to the ForegroundServiceManager in your code if you called getForegroundServiceManager. This should typically only be called if you want to modify a previously set default message or resume intent.

public static synchronized ForegroundServiceManager getForegroundServiceManager (Application application)

Obtains the singleton ForegroundServiceManager instance. If #initForegroundServiceManager is not called before getForegroundServiceManager(Application), a default notification ID, message and notification provider will be used.

Parameters
application the current Application

public static String getNavSDKVersion ()

Returns the current NavSDK version.

public static void getNavigator (Application application, NavigationApi.NavigatorListener callback)

Obtains the Navigator instance.

If the user has not yet agreed to the terms and conditions, the callback will immediately be fired with the error code NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED.

Note that Navigator is a singleton; if you call this method multiple times, each call will return the same Navigator.

Parameters
application the current Application
callback a callback which will be fired when the Navigator is ready, or an error occurs

public static void getNavigator (Activity activity, NavigationApi.NavigatorListener callback, TermsAndConditionsCheckOption termsCheck)

Obtains the Navigator instance.

If the user has not yet agreed to the terms and conditions, this call shows a dialog that prompts the user to agree to the terms and conditions of use.

If termsCheck is TermsAndConditionsCheckOption.ENABLED, the dialog also contains a link to the Terms and Conditions for the Navigation SDK. The callback is called with a NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED error if the user fails to accept these terms.

Enforces terms and conditions in two cases: if your project does not have permissions to skip terms and conditions enforcement using TermsAndConditionsCheckOption.SKIPPED, OR the Navigation SDK fails to read your project properties.

Note that Navigator is a singleton; if you call this method multiple times, each call will return the same Navigator.

Parameters
activity the Activity to show the terms and conditions dialog on, if they have not yet been accepted
callback a callback which will be fired when the Navigator is ready, or an error occurs
termsCheck indicating whether the Terms and Conditions check should be skipped

public static void getNavigator (Activity activity, NavigationApi.NavigatorListener callback)

Equivalent to getNavigator(activity, callback, termsCheck) in which termsCheck is TermsAndConditionsCheckOption.ENABLED.

Parameters
activity the Activity to show the terms and conditions dialog on, if they have not yet been accepted
callback a callback which will be fired when the Navigator is ready, or an error occurs

public static void getNavigatorNoToS (Application application, NavigationApi.NavigatorListener callback)

Obtains the Navigator instance.

Bypasses the terms and conditions only if your project is granted permissions to skip the terms and condition enforcement using TermsAndConditionsCheckOption.SKIPPED.

Enforces terms and conditions in two cases: if your project does not have permissions to skip terms and conditions enforcement using TermsAndConditionsCheckOption.SKIPPED, OR the Navigation SDK fails to read your project properties.

Note that Navigator is a singleton; if you call this method multiple times, each call will return the same Navigator.

Parameters
application the current Application.
callback a callback which will be fired when the Navigator is ready, or an error occurs.

public static RoadSnappedLocationProvider getRoadSnappedLocationProvider (Application application)

Obtains an instance of the RoadSnappedLocationProvider, which can be used to subscribe to road-snapped user locations. Note that subscribing to road-snapped location updates may cause battery drain or unintentional collection of user location data if left running in the background.

A Navigator must be successfully obtained before calling this method, otherwise it will return null.

Parameters
application the current Application

public static NavigationTransactionRecorder getTransactionRecorder (Application application)

Obtains an instance of the NavigationTransactionRecorder, which can be used to record transactions related to navigation.

This method should only be used by Mobility Services customers.

A Navigator must be successfully obtained before calling this method, otherwise it will return null.

If your project configuration prevents calling this method, it will return a no-op NavigationTransactionRecorder.

Parameters
application the current Application

public static synchronized void initForegroundServiceManagerMessageAndIntent (Application application, Integer notificationId, String defaultMessage, Intent resumeIntent)

Initializes the ForegroundServiceManager instance with arguments for setting the default message and resume intent.

This should only be called to modify the default parameters. Otherwise, call getForegroundServiceManager(Application) directly. This method must only be called once and must be called before getForegroundServiceManager(Application). If you wish to change the default message or resume intent after initializing it, you must call clearForegroundServiceManager before calling this method again.

Note that invoking this method will create a navigator, if one does not already exist.

Parameters
application the current Application.
notificationId notification ID for the persistent notification. Use null to use the default navigation notification ID.
defaultMessage default message to be shown if a provider is not specified. Use null to use the standard navigation default message.
resumeIntent Intent to fire when notification is clicked. Use null to ignore clicks on the notification.
Throws
if this method has already been called and clearForegroundServiceManager has not been called.

public static synchronized void initForegroundServiceManagerProvider (Application application, Integer notificationId, NotificationContentProvider provider)

Initializes the ForegroundServiceManager instance with a provider that specifies notification content.

This method is typically only called once and must be called before getForegroundServiceManager(Application). If you wish to change the provider after initializing it, you must call clearForegroundServiceManager before calling this method again.

Note that invoking this method will create a navigator, if one does not already exist.

Parameters
application the current Application.
notificationId notification ID for the persistent notification. Use null to use the default navigation notification ID.
provider an implementation of NotificationContentProvider

public static void resetTermsAccepted (Application application)

Reset the terms and conditions - for testing. Add a call to this before any calls to NavigationApi if you want to test the terms and conditions dialog.

Parameters
application the current application

public static void setAbnormalTerminationReportingEnabled (boolean enabled)

Enables/disables reporting abnormal SDK terminations such as the app crashes while the SDK is still running. This allows Google to improve SDK stability when applicable. The default is true and value must be updated before any SDK usage.

Parameters
enabled whether abnormal SDK terminations should be reported.

public static void showTermsAndConditionsDialog (Activity activity, String companyName, String title, NavigationApi.OnTermsResponseListener listener)

Displays a dialog that directs the user to accept Google's Navigation terms and conditions, using the default look and feel.

Parameters
activity the Activity on which the dialog will be shown
companyName your company name, which will be displayed in the terms and conditions dialog. If null, the dialog will use the application name.
title the title of the dialog.
listener an optional callback which will be fired when the user accepts or declines the terms and conditions

public static void showTermsAndConditionsDialog (Activity activity, String companyName, String title, TermsAndConditionsUIParams uiParams, NavigationApi.OnTermsResponseListener listener, TermsAndConditionsCheckOption termsAndConditionsCheckOption)

Displays a dialog that directs the user to accept Google's Navigation terms and conditions. If specified, the listener will be called on the UI thread, indicating whether the user accepts the terms and conditions.

Note that the dialog will appear even if the user has previously accepted. This should only be called if areTermsAccepted(Application) is false, because it is not possible for a user to un-accept the terms and conditions.

If your project prevents the use of TermsAndConditionsCheckOption.SKIPPED or the Navigation SDK fails to read your project properties, the TermsAndConditionsCheckOption.ENABLED option is enforced.

Parameters
activity the Activity on which the dialog will be shown
companyName your company name, which will be displayed in the terms and conditions dialog. If null, the dialog will use the application name.
title the title of the dialog. If null, the dialog will use the default title.
uiParams the parameters used to customize the look and feel of the dialog. If null, the default look and feel is used.
listener an optional callback which will be fired when the user accepts or declines the terms and conditions
termsAndConditionsCheckOption the TermsAndConditionsCheckOption which specifies options for checking terms and conditions

public static void showTermsAndConditionsDialog (Activity activity, String companyName, NavigationApi.OnTermsResponseListener listener)

Displays a dialog that directs the user to accept Google's Navigation terms and conditions, using the default title and the default look and feel.

Parameters
activity the Activity on which the dialog will be shown
companyName your company name, which will be displayed in the terms and conditions dialog. If null, the dialog will use the application name.
listener an optional callback which will be fired when the user accepts or declines the terms and conditions