> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/ja/navigation/v2/llms.txt)

# Route replay

Testing and previewing the navigation experience is an important part of building with the Navigation SDK. For example, you may want to investigate how turn-by-turn navigation performed during test rides as you develop, test, and demo your work. You can use the SDK's route replay functionality to go back in time and replay real rides.

### Implement replay

The Navigation SDK's replay framework is comprised of two core classes:

-   [`MapboxReplayer`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-mapbox-replayer/) handles shifting historical event timestamps into real-time events.
-   [`ReplayEventBase`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay.history/-replay-event-base/) is an interface for anything with a time unit. The time basis can be months in the past, in the future, or starting at `0.0`.

There are also several helper classes you can use to create and listen to replay events:

-   [`ReplayHistoryMapper`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay.history/-replay-history-mapper/) converts history files into replay events.
-   [`ReplayLocationEngine`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-replay-location-engine/) extends the Android system's `LocationEngine` class. It observes the `ReplayEventUpdateLocation` and passes the location to `MapboxNavigation`.
-   [`ReplayRouteMapper`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay.route/-replay-route-mapper/) converts a `DirectionsResponse` into replay events.
-   [`ReplayProgressObserver`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay.route/-replay-progress-observer/) observes `MapboxNavigation` and simulates route progress.

### Record and use history files

#### Record a history file

To record a trip as a history file:

1.  (Optional) Specify history file location using [`HistoryRecorderOptions`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-base/com.mapbox.navigation.base.options/-history-recorder-options/):
    
    ```kotlin
    mapboxNavigation = MapboxNavigation(
      NavigationOptions.Builder(this)
          ...
          .historyRecorderOptions(
              HistoryRecorderOptions.Builder()
                  .fileDirectory(myDirectory)
                  .build()
          )
          ...
          .build()
    )
    ```
    
    You can skip this step, then the default location (`<app_directory>/files/mbx_nav/history`) will be used.
    
2.  Start recording:
    
    ```kotlin
    mapboxNavigation.historyRecorder.startRecording()
    ```
    
3.  Stop recording and the history file will be available in the path returned:
    
    ```kotlin
    mapboxNavigation.historyRecorder.stopRecording { filePath ->
        if (filePath != null) {
            // move to a different path or upload to the cloud
        }
    }
    // optionally, immediately start the next recording session outside of the callback:
    mapboxNavigation.historyRecorder.startRecording()
    ```
    

#### Retrieve history files

There are two ways to retrieve a recorded history file to be used on a device:

-   Store the JSON file in a directory and read the file. The Navigation SDK test app's [`ReplayHistoryActivity` example](https://github.com/mapbox/mapbox-navigation-android/blob/v2.22.2/examples/src/main/java/com/mapbox/navigation/examples/core/ReplayHistoryActivity.kt) uses this approach. The file is stored in the app's [assets folder](https://github.com/mapbox/mapbox-navigation-android/blob/v2.22.2/examples/src/main/assets).
-   Host history files somewhere in a cloud-based backend database (for example Firebase, Amazon Web Services, or GitHub Pages).

#### Replay history data

After you've retrieved the history file, you can replay the history data using [`MapboxReplayer`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-mapbox-replayer/):

1.  Map the history string to replay events using [`ReplayHistoryMapper`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay.history/-replay-history-mapper/).
2.  Push the events into the [`MapboxReplayer.pushEvents(..)`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-mapbox-replayer/push-events.html).
3.  Substitute your `LocationEngine` with a [`ReplayLocationEngine`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-replay-location-engine/).
4.  Call [`MapboxReplayer.play()`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-mapbox-replayer/play.html).

5.  When done call [`MapboxReplayer.finish()`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-mapbox-replayer/finish.html) to stop and clean up the replayer.

> **Related content (example): [Replay history](https://github.com/mapbox/mapbox-navigation-android/blob/v2.22.2/examples/src/main/java/com/mapbox/navigation/examples/core/ReplayHistoryActivity.kt)**
> 
> Replay history using real data by reading a history string from a file and replaying it with the Navigation SDK.

### Create custom events

You can create custom events and play them on their own or play them through history files.

#### Replay custom events

You can replay any event to test on its own (without a history file), for example a map gesture event or zooming in and out of the map.

Start by setting up a custom event that implements [`ReplayEventBase`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay.history/-replay-event-base/). `ReplayEventBase` is a base interface event that can be implemented with any event you want to test:

```kotlin
private data class ReplayEventInitialRoute(
    override val eventTimestamp: Double,
    val coordinates: List<LatLng>
) : ReplayEventBase
```

Then, set up the `MapboxReplayer` and `ReplayHistoryMapper` classes:

```kotlin
val mapboxReplayer = MapboxReplayer()

val replayHistoryMapper = ReplayHistoryMapper(customEventMappper, logger)
```

Create a `ReplayHistoryLocationEngine` object and give it to `MapboxNavigation` via the `NavigationOptions` when you build a `MapboxNavigation` object. This way, `MapboxNavigation` will use the `Location` objects:

```kotlin
val navigationOptions = NavigationOptions.Builder(context)
	.accessToken("token")
	.locationEngine(ReplayLocationEngine(mapboxReplayer))
	.build()
	
mapboxNavigation = MapboxNavigation(navigationOptions)
```

Get history events:

```kotlin
val replayEvents = replayHistoryMapper.mapToReplayEvents(rideHistoryExampleJsonString)
```

Then, you can give the custom event to the [`MapboxReplayer`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.replay/-mapbox-replayer/) via `MapboxReplayer.pushEvents()`:

```kotlin
mapboxReplayer.pushEvents(replayEvents)
```

The `MapboxReplayer` also has a `seekTo()` method function to move the player to timestamp that you want to play.

Finally, start replaying the events:

```kotlin
playReplay.setOnClickListener {
	mapboxReplayer.play(context)
}
```

#### Replay custom events from history files

Navigation history files have several predefined events, which can be retrieved with the `MapboxNavigation` class:

```kotlin
val historyString = mapboxNavigation.retrieveHistory()
```

Custom events can also be created and added to the history file:

```kotlin
mapboxNavigation.addHistoryEvent(eventTypeString, eventJsonProperties)
```

You must create a custom class that implements the Navigation SDK's `CustomEventMapper` interface to replay the history file's custom events.

```kotlin
private class ReplayCustomEventMapper : CustomEventMapper {
    override fun map(eventType: String, event: LinkedTreeMap<*, *>): ReplayEventBase? {
        return when (eventType) {
            "initial_route" -> {
                val properties = event["properties"] as LinkedTreeMap<*, *>
                val routeOptions = properties["routeOptions"] as LinkedTreeMap<*, *>
                val coordinates = routeOptions["coordinates"] as List<List<Double>>
                val coordinatesLatLng = coordinates.map { LatLng(it[1], it[0]) }
                ReplayEventInitialRoute(
                        eventTimestamp = event["event_timestamp"] as Double,
                        coordinates = coordinatesLatLng
                )
            }
            else -> null
        }
    }
}
```