Developer

Saving and resuming navigation

VERSION 2.1.2

This guide describes features that are part of the Maps and Navigation SDK Extended flavor, available upon request. Contact us to get started.

If the NavigationVisualization object is used, make sure the NavigationResumeSnapshotRenewer object is initialized after it.

Whether the app crashes, is accidentally terminated, or the system reclaims resources, saving an ongoing navigation session allows TomTomNavigation to restore its previous state when the app is restarted.

To support session restoration, TomTomNavigation provides the TomTomNavigation.navigationResumeSnapshot property and the TomTomNavigation.resume(navigationResumeSnapshot: NavigationResumeSnapshot) method. To serialize a NavigationResumeSnapshot, use the NavigationResumeSnapshot.serializeToFile(snapshotFle: File) or NavigationResumeSnapshot.serializeToBytes() methods. To deserialize it, use the NavigationResumeSnapshot.deserializeFromFile(file: File) or NavigationResumeSnapshot.deserializeFromBytes(data: byteArray) method.

You can save and resume a navigation session either automatically or manually.

Saving and resuming a navigation session automatically

To start saving navigation data automatically, create a default implementation of NavigationResumeSnapshotRenewer. Once navigation starts, a snapshot is saved periodically—every 30 seconds by default.

1val navigationResumeSnapshotRenewer =
2    NavigationResumeSnapshotRenewerFactory.create(
3        context = context,
4        options = NavigationResumeSnapshotRenewerOptions(),
5        tomTomNavigation = tomTomNavigation,
6    )

The automatic saving interval is configured through NavigationResumeSnapshotRenewerOptions as shown below:

1val options = NavigationResumeSnapshotRenewerOptions(saveInterval = 40.seconds)
2val navigationResumeSnapshotRenewer =
3    NavigationResumeSnapshotRenewerFactory.create(
4        context = context,
5        options = options,
6        tomTomNavigation = tomTomNavigation,
7    )

To automatically resume a previously saved session, use the NavigationResumeSnapshotRenewer.resumeNavigation() method:

1navigationResumeSnapshotRenewer.resumeNavigation(
2    callback =
3        object :
4            Callback<NavigationResumeSnapshot, NavigationResumeSnapshotRenewerFailure> {
5            override fun onSuccess(result: NavigationResumeSnapshot) {
6                // YOUR CODE GOES HERE
7            }
8

9            override fun onFailure(failure: NavigationResumeSnapshotRenewerFailure) {
10                // YOUR CODE GOES HERE
11            }
12        },
13)

To resume a previously saved session manually, use the NavigationResumeSnapshotRenewer.latestNavigationResumeSnapshot() method:

1navigationResumeSnapshotRenewer.latestNavigationResumeSnapshot(
2    callback =
3        object :
4            Callback<NavigationResumeSnapshot, NavigationResumeSnapshotRenewerFailure> {
5            override fun onSuccess(result: NavigationResumeSnapshot) {
6                tomTomNavigation.resume(result)
7                // YOUR CODE GOES HERE
8            }
9

10            override fun onFailure(failure: NavigationResumeSnapshotRenewerFailure) {
11                // YOUR CODE GOES HERE
12            }
13        },
14)

Saving and resuming a navigation session manually

To manually save a NavigationResumeSnapshot to a file, use the following snippet:

1val fileName = "navigation_snapshot"
2tomTomNavigation.navigationResumeSnapshot()
3    .ifSuccess { snapshot ->
4        snapshot.serializeToBytes() // or snapshot.serializeToFile(file)
5            .ifSuccess { data ->
6                val file = File(context.filesDir, fileName)
7                FileOutputStream(file).use { fileOutputStream ->
8                    fileOutputStream.write(data)
9                }
10            }
11            .ifFailure { failure: NavigationResumeSnapshotSerializationFailure ->
12                // YOUR CODE GOES HERE
13            }
14    }
15    .ifFailure { failure: NavigationResumeSnapshotFailure ->
16        // YOUR CODE GOES HERE
17    }

To resume a previously saved session from a file, use the following snippet:

1val fileName = "navigation_snapshot"
2val file = File(context.filesDir, fileName)
3if (file.exists()) {
4    NavigationResumeSnapshot.deserializeFromFile(file)
5        .ifSuccess { snapshot ->
6            tomTomNavigation.resume(navigationResumeSnapshot = snapshot)
7        }
8        .ifFailure { failure: NavigationResumeSnapshotSerializationFailure ->
9            // YOUR CODE GOES HERE
10        }
11}

After resuming, the RouteAddedListener is invoked with the RouteAddedReason argument set to RouteAddedReason.NavigationResumed. The TomTomNavigation.language and TomTomNavigation.configuration.unitSystem are also restored from the previous session.

You can apply a new language via the TomTomNavigation and unitSystem via the TomTomNavigation.configuration.update after resuming the session.

To improve performance, save the NavigationResumeSnapshot after key events that result in significant changes to the navigation state, such as:

  • Starting navigation along a route
  • Refreshing the route
  • Deviating from the route
  • Visiting a waypoint