Journey Android

Setup

Add the following dependencies in the build.gradle file of your application:

dependencies {
    implementation("com.kisio.navitia.sdk.ui:journey:5.17.3")
}

For the use of cartography, add your Google Maps API Key to your AndroidManifest.xml as well. Replace YOUR_API_KEY with your key:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_API_KEY"/>

The activity launching Journey must handle the following configuration changes: orientation|screenSize declared into your AndroidManifest.xml:

<activity
    android:configChanges="orientation|screenSize"/>

Implementation

Warning

Make sure to read the modules configuration section before proceeding!

This module is set up by calling JourneyUI.getInstance(). The singleton behaves like a builder in which each method allows you to configure the module. Then, you need to call the init() method at the end. You should call this method in an Application subclass.
This method takes the following parameters:

Name	Description	Type	Default
`context`	Context in which the module is launched	`Context`
`token`	Get your token	`String`
`configuration`	Module configuration object	`JourneyConfiguration`	`null`
`configurationJsonFile`	Module configuration JSON file name	`String`	`null`

Example

Configuration with fileManual configuration

JourneyUI.getInstance().let { instance ->
    instance.init(
        context = this,
        token = "your_token",
        configurationJsonFile = "config.json"
    )
}

JourneyUI.getInstance().let { instance ->
    instance.init(
        context = this,
        token = "your_token",
        configuration = JourneyConfiguration(
            coverage = "your_coverage",
            timezone = "Europe/Paris",
            env = JourneyEnvironment.PROD,
            colors = JourneyColors(
                primary = "#88819f"
            ),
            transportCategories = listOf<JourneyTransportCategory>()
        )
    )
}

Since the module launches its own fragments, you may want your application to be aware of navigation events. For that, you have to set a navigation listener by calling this method before init().

JourneyUI.getInstance()
    .setNavigationListener(journeyNavigationListenerImpl) // (1)

journeyNavigationListenerImpl should be the class instance implementing JourneyNavigationListener interface.

This interface gives you the method onBack() for any back event between two fragments and the method onNavigate for the reverse. Each method has a JourneyNavigationListener.Event parameter you can rely on.

// Navigation events
EXTERNAL_TO_JOURNEYS
EXTERNAL_TO_ROADMAP
GUIDANCE_BACK_TO_ROADMAP
JOURNEYS_BACK_TO_EXTERNAL
JOURNEYS_TO_RIDESHARING
JOURNEYS_TO_ROADMAP
RIDESHARING_BACK_TO_JOURNEYS
RIDESHARING_TO_ROADMAP
ROADMAP_TO_GUIDANCE
ROADMAP_BACK_TO_EXTERNAL
ROADMAP_BACK_TO_JOURNEYS
ROADMAP_BACK_TO_RIDESHARING

Events tracking

In order to receive the list of generated events within Journey module, you have to attach the tracker to the module instance.
You can call this method before or after init().

JourneyUI.getInstance()
    .attachTracker(journeyTrackerImpl) // (1)

journeyTrackerImpl should be the class instance implementing JourneyTracker interface.

Launching

Journey has a single entry point JourneysFragment.
Assuming you have an Activity with a fragment container, refer to the following example to launch the entry screen fragment:

supportFragmentManager.beginTransaction().run {
    replace(
        R.id.container_id,
        JourneysFragment.newInstance(journeysRequest = JourneysRequest(), showBack = false),
        "TAG"
    )
    addToBackStack("TAG")
    commit()
}

The newInstance() method creates an instance of the target fragment and takes the following parameters:

Name	Required	Description	Type	Default
`journeysRequest`		Itinerary search configuration	`JourneysRequest`
`showBack`		Show/hide back button on the first screen	`Boolean`	`false`

`JourneysRequest`

The JourneysRequest object allows to configure the first itinerary search at screen launch. It has the following parameters:

Name	Description	Type	Default
`additionalTimeAfterFirstSectionTaxi`	Additional time after first taxi section	`Int`	`null`
`additionalTimeBeforeLastSectionTaxi`	Additional time before last taxi section	`Int`	`null`
`allowedId`	Allowed Navitia object IDs	`List<String>`	`emptyList()`
`bikeSpeed`	Bike speed	`Float`	`null`
`bssSpeed`	BSS speed	`Float`	`null`
`carNoParkSpeed`	Car no park speed	`Float`	`null`
`carSpeed`	Car speed	`Float`	`null`
`count`	The number of journeys to be displayed	`Int`	`-1`
`dataFreshness`	To indicate if theoretical or realtime data are requested	`DataFreshness`	`DataFreshness.BASE_SCHEDULE`
`dateTime`	Requested date and time for journey results	`DateTime`	`null`
`dateTimeRepresents`	Whether the datetime represents the departure or arrival	`DateTimeRepresents`	`DateTimeRepresents.DEPARTURE`
`depth`	The request depth	`Int`	`null`
`destinationId`	Destination Navitia ID	`String`	`""`
`destinationLabel`	Destination label, if not set the address will be displayed	`String`	`""`
`directPath`	Set the direct path of the journey	`DirectPath`	`""`
`disruptionActive`	Check on Navitia	`Boolean`	`null`
`equipmentDetails`	Check on Navitia	`Boolean`	`null`
`freeRadiusFrom`	Check on Navitia	`Int`	`null`
`freeRadiusTo`	Check on Navitia	`Int`	`null`
`isJourneySchedules`	Check on Navitia	`Boolean`	`null`
`maxBikeDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxBikeDurationToPt`	Check on Navitia	`Int`	`null`
`maxBssDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxBssDurationToPt`	Check on Navitia	`Int`	`null`
`maxCarDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxCarDurationToPt`	Check on Navitia	`Int`	`null`
`maxCarNoParkDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxCarNoParkDurationToPt`	Check on Navitia	`Int`	`null`
`maxDuration`	Check on Navitia	`Int`	`null`
`maxDurationToPt`	Check on Navitia	`Int`	`null`
`maxJourneys`	The max number of journeys to be displayed	`Int`	`-1`
`maxNbTransfers`	The max number of public transport transfers	`Int`	`-1`
`maxRidesharingDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxRidesharingDurationToPt`	Check on Navitia	`Int`	`null`
`maxTaxiDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxTaxiDurationToPt`	Check on Navitia	`Int`	`null`
`maxWaitingDuration`	Check on Navitia	`Int`	`null`
`maxWalkingDirectPathDuration`	Check on Navitia	`Int`	`null`
`maxWalkingDurationToPt`	Check on Navitia	`Int`	`null`
`minJourneys`	The min number of journeys to be displayed	`Int`	`-1`
`minNbTransfers`	The min number of public transport transfers	`Int`	`-1`
`originId`	Origin Navitia ID	`String`	`""`
`originLabel`	Origin label, if not set the address will be displayed	`String`	`""`
`ridesharingSpeed`	Ridesharing speed	`Float`	`null`
`taxiSpeed`	Taxi speed	`Float`	`null`
`timeframeDuration`	Taxi speed	`Int`	`null`
`travelerType`	Traveler type	`TravelerType`	`TravelerType.STANDARD`
`walkingSpeed`	Walking speed	`Float`	`null`
`wheelchair`	Check on Navitia	`Boolean`	`null`

`DataFreshness`

Enum value	Description
`BASE_SCHEDULE`	Get disrupted journeys with the given results
`REALTIME`	Avoid disrupted journeys

`DateTimeRepresents`

Enum value	Description
`ARRIVAL`	The requested datetime represents the arrival of the journey
`DEPARTURE`	The requested datetime represents the departure of the journey

`DirectPath`

Enum value	Description
`INDIFFERENT`	Default value
`NONE`	For journeys using some public transport
`ONLY`	For journeys without public transport
`ONLY_WITH_ALTERNATIVES`	For journeys with specific bike

`TravelerType`

Enum value	Description
`FAST`	Fast walker
`LUGGAGE`	With luggage
`SLOW`	Slow walker
`STANDARD`	Standard profile
`WHEELCHAIR`	Using wheelchair

Communicating with other modules or the app

Journey module can exchange data with or navigate to either other modules or the host application.
To do this, the host application must initialize Router. This singleton will ensure communication between the different modules or the app. Communication will not occur unless those are registered beforehand:

Router.getInstance()
    ... // Register modules and/or app
    .init()

Application

Some routes or callbacks are delegated to the application. If you have to receive some module data, the Router module must register a receiver with the right parameter:

Router.getInstance()
    .register(appData = appRouterDataImpl) // (1)

appRouterDataImpl should be the class instance implementing AppRouter.Data interface. We recommand usign a Application subclass.

If you have to handle navigation between modules, the Router module must also register a receiver:

Router.getInstance()
    .register(appUi = appRouterUiImpl) // (1)

appRouterUiImpl should be the class instance implementing AppRouter.UI interface. We recommand usign a Application subclass.

Result journeys / Roadmap view injection

You can inject some external view that will be shown inside the journey module screens. In order to make it happen, you need to add the reference to the injectableViewDelegate as follows:

JourneyUI.getInstance().setInjectableViewDelegate(this)

The interface provides the following methods:

override fun allowExternalViewInjectionFor(screen: InjectableScreen, inputData: Any?): ExternalViewInjectionState {
    // Allow or not the external view injection
}

override fun buildExternalViewFor(screen: InjectableScreen, inputData: Any?): View? {
    // Put the view that needs to be injected in the injectable screen
}

Note

inputData can be of type:

SharedJourneysScreenData if the injectable screen is LIST_JOURNEYS
SharedRoadmapScreenData if the injectable screen is ROADMAP

SharedJourneysScreenData

Name	Description	Type
`journeysRequest`	The request parameters object	`JourneysRequest`
`hasResults`	Whether the request has results or not	`Boolean`
`selectedFilterType`	The selected tab	`TransportModesFilterType`

SharedRoadmapScreenData

Name	Description	Type
`journeysRequest`	The request parameters object	`JourneysRequest`
`selectedJourney`	The selected journey data	`SharedSelectedJourneyModel`

SharedSelectedJourneyModel

Name	Description	Type
`departureTime`	The departure time	`LocalDateTime`
`arrivalTime`	The arrival time	`LocalDateTime`
`departureAddress`	The departure address	`String`
`arrivalAddress`	The arrival address	`String`
`departureCoordinates`	The departure coordinates	`LatLng`
`arrivalCoordinates`	The arrival coordinates	`LatLng`
`sections`	The list of journey sections	`List<SectionModel>`

SectionModel

Name	Description	Type
`departureTime`	The departure time	`LocalDateTime`
`arrivalTime`	The arrival time	`LocalDateTime`
`departureAddress`	The departure address	`String`
`arrivalAddress`	The arrival address	`String`
`departureCoordinates`	The departure coordinates	`LatLng?`
`arrivalCoordinates`	The arrival coordinates	`LatLng?`
`mobilityType`	The mobility type	`MobilityType`
`distance`	The distance in meters	`Int`
`duration`	The duration in seconds	`Int`
`additionalInformation`	The extra section information if the mobility type allows it	`Any?`

Note

additionalInformation object in SectionModel can be of type:

StreetNetworkSectionModel if the mobilityType is STREET_NETWORK
PublicTransportSectionModel if the mobilityType is PUBLIC_TRANSPORT
CarParkingSectionModel if the mobilityType is CAR_PARKING

Roadmap actions

You can add some actions to the roadmap screen which can be configured using this appropriate delegate:

JourneyUI.getInstance().setRoadmapDelegate(this)

The implemented interface offers the following methods:

override fun allowedRoadmapScreenActionsFor(inputData: SharedRoadmapScreenData) {
    // Define the allowed actions on the roadmap screen
}

override fun onPrimaryButtonActionTriggered(inputData: SharedRoadmapScreenData) {
    // Handle primary action button click
}

override fun onSecondaryButtonActionTriggered(inputData: SharedRoadmapScreenData) {
    // Handle secondary action button click
}

A journey may include sections for driving, walking, or cycling. This module provides the option in the Roadmap screen to enhance navigation accuracy using data from an external service.
To enable this feature, first enable the external_navigation parameter in the features configuration. Then, implement the following method:

override fun openExternalNavigation(
    fromCoords: LatLng,
    fromLabel: String,
    toCoords: LatLng,
    toLabel: String,
    mode: ExternalNavigationMode
) {
    // launch your external navigation service screen or your custom screen
}

Param	Type	Description
`fromCoords`	`LatLng`	Section departure coordinates
`fromLabel`	`String`	Section departure label
`toCoords`	`LatLng`	Section arrival coordinates
`toLabel`	`String`	Section arrival label
`mode`	`ExternalNavigationMode`	Section navigation mode

Note

ExternalNavigationMode has 3 modes of transportation that describe the section: BIKE, CAR, and WALKING.

Modules

Bookmark

Enabling

This module communicates with Bookmark module in order to display favorite stations, journeys and POIs. You should enable the bookmark_mode parameter in the features configuration.

Methods

The following methods from the AppRouter.UI interface should be implemented by the host application to enable navigation to the Bookmark module or any other custom screen. Note that the parameters of these methods can be omitted as needed.

override fun openFavoriteHomeAddViaHost(linkedModule: BookmarkLinkedModule) {
    // launch the bookmark module screen or your custom screen
}

Param	Type	Description	Value
`linkedModule`	`BookmarkLinkedModule`	Module triggering the method call	`BookmarkLinkedModule.AROUND_ME` or `BookmarkLinkedModule.JOURNEY`

override fun openFavoriteWorkAddViaHost(linkedModule: LinkedModule) {
    // launch the bookmark module screen or your custom screen
}

Param	Type	Description	Value
`linkedModule`	`BookmarkLinkedModule`	Module triggering the method call	`BookmarkLinkedModule.AROUND_ME` or `BookmarkLinkedModule.JOURNEY`

Theming

App theme

The module uses graphical components from Material Design 3. To ensure these components function correctly and get displayed properly on the screen, it is crucial to apply the appropriate parent theme:

<style name="Theme.App" parent="Theme.Material3.*"> <!-- (1) -->
    ...
</style>

Replace by the specific theme. For example: Theme.Material3.Light.NoActionBar

Date time picker

The date time picker theme in the Journeys screen is set by the system and cannot really offer yet some flexibility. If a dark mode is applied on the phone, the system will apply predefined colors regardless of the configured colors.
If you want to theme the date time picker, you can only add the following in your style or theme file of your app:

<style name="Journey.DateTimePicker" parent="ThemeOverlay.Material3.MaterialCalendar">
    <item name="colorAccent">#251942</item> <!--header background-->
    <item name="android:windowBackground">#FFFFFF</item> <!--calendar background-->
    <item name="android:colorControlActivated">#251942</item> <!--selected day-->
</style>

Journey Android

Setup

Implementation

Example

Navigation listener

Events tracking

Launching

`JourneysRequest`

`DataFreshness`

`DateTimeRepresents`

`DirectPath`

`TravelerType`

Communicating with other modules or the app

Application

Result journeys / Roadmap view injection

Roadmap actions

Roadmap navigation

Modules

Bookmark

Theming

App theme

Date time picker