Saving and resuming navigation

VERSION 2.3.0-rc03

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.

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.

1
val 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:

1
val options = NavigationResumeSnapshotRenewerOptions(saveInterval = 40.seconds)
2
val 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:

1
navigationResumeSnapshotRenewer.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:

1
navigationResumeSnapshotRenewer.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
)

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

1
val fileName = "navigation_snapshot"
2
tomTomNavigation.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:

1
val fileName = "navigation_snapshot"
2
val file = File(context.filesDir, fileName)
3
if (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

Saving and resuming navigation

Saving and resuming a navigation session automatically

Saving and resuming a navigation session manually