Bookmark Android

Setup

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

dependencies {
    implementation("com.kisio.navitia.sdk.ui:bookmark:1.12.0")
}

The activity launching Bookmark 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 BookmarkUI.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	Required	Description	Type	Default
context		Context in which the module is launched	Context
token		Get your token	String
configuration		Module configuration object	AroundMeConfiguration	null
configurationJsonFile		Module configuration JSON file name	String	null

Example

Configuration with fileManual configuration

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

BookmarkUI.getInstance().let { instance ->
    instance.init(
        context = this,
        token = "your_token",
        configuration = BookmarkConfiguration(
            coverage = "your_coverage",
            timezone = "Europe/Paris",
            env = BookmarkEnvironment.PROD,
            colors = BookmarkColors(
                primary = "#88819f"
            )
        )
    )
}

Navigation listener

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().

BookmarkUI.getInstance()
    .setNavigationListener(bookmarkNavigationListenerImpl) // (1)

1. bookmarkNavigationListenerImpl should be the class instance implementing BookmarkNavigationListener 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 BookmarkNavigationListener.Event parameter you can rely on.

// Navigation events
ADD_ADDRESS_BACK_TO_FAVORITES
EXTERNAL_TO_ADD_ADDRESSES
EXTERNAL_TO_FAVORITES
FAVORITES_BACK_TO_EXTERNAL
FAVORITES_TO_JOURNEY
FAVORITES_TO_ADD_ADDRESS
FAVORITES_TO_ROADMAP

Events tracking

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

BookmarkUI.getInstance()
    .attachTracker(bookmarkTrackerImpl) // (1)

1. bookmarkTrackerImpl should be the class instance implementing BookmarkTracker interface.

Launching

Bookmark has a single entry point FavoriteFragment.
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, FavoriteFragment.newInstance(), "TAG")
    addToBackStack("TAG")
    commit()
}

Manipulating data

The module provides the ability to directly manipulate data for use in custom screens.

Methods

The various CRUD methods are accessed through BookmarkUI.getInstance().data.

Create

Create a new favorite address

fun saveAddress(address: SharedData.AddressBookmark)

Param	Type	Description
address	SharedData.AddressBookmark	Favorite address to create

Create a new favorite journey

fun saveJourney(journey: SharedData.JourneyBookmark)

Param	Type	Description
journey	SharedData.JourneyBookmark	Favorite journey to create

Create a new favorite POI

fun savePoi(poi: SharedData.PoiBookmark)

Param	Type	Description
poi	SharedData.PoiBookmark	Favorite POI to create

Create a new favorite station

fun saveStation(station: SharedData.StationBookmark)

Param	Type	Description
station	SharedData.StationBookmark	Favorite station to create

Read

Fetch a favorite address data. Returns SharedData.AddressBookmark or null if not found.

fun fetchAddress(id: String): SharedData.AddressBookmark?

Param	Type	Description
id	String	Id of the favorite address to fetch

Fetch all favorite addresses. Returns a list of SharedData.AddressBookmark or an empty list if there is no data.

fun fetchAddresses(): List<SharedData.AddressBookmark>

Fetch a favorite journey data. Returns SharedData.JourneyBookmark or null if not found.

fun fetchJourney(travelId: String): SharedData.JourneyBookmark?

Param	Type	Description
travelId	String	Travel id of the favorite journey to fetch

Fetch all favorite journeys. Returns a list of SharedData.JourneyBookmark or an empty list if there is no data.

fun fetchJourneys(): List<SharedData.JourneyBookmark>

Fetch a favorite POI data. Returns SharedData.PoiBookmark or null if not found.

fun fetchPoi(id: String): SharedData.PoiBookmark?

Param	Type	Description
id	String	Id of the favorite POI to fetch

Fetch all favorite POIs. Returns a list of SharedData.PoiBookmark or an empty list if there is no data.

fun fetchPois(): List<SharedData.PoiBookmark>

Fetch a favorite station data. Returns SharedData.StationBookmark or null if not found.

fun fetchStation(stopAreaId: String, lineId: String): SharedData.StationBookmark?

Param	Type	Description
stopAreaId	String	Navitia stop area id of the favorite station to fetch
lineId	String	Navitia line id of the favorite station to fetch

Fetch all favorite stations. Returns a list of SharedData.StationBookmark or an empty list if there is no data.

fun fetchStations(): List<SharedData.StationBookmark>

Update

Update an existing favorite address

fun updateAddress(address: SharedData.AddressBookmark)

Param	Type	Description
address	SharedData.AddressBookmark	Favorite address to update

Update an existing favorite journey

fun updateJourney(journey: SharedData.JourneyBookmark)

Param	Type	Description
journey	SharedData.JourneyBookmark	Favorite journey to update

Update an existing favorite POI

fun updatePoi(poi: SharedData.PoiBookmark)

Param	Type	Description
poi	SharedData.PoiBookmark	Favorite poi to update

Update an existing favorite station

fun updateStation(station: SharedData.StationBookmark)

Param	Type	Description
station	SharedData.StationBookmark	Favorite station to update

Delete

Delete an existing favorite address

fun deleteAddress(id: String)

Param	Type	Description
id	String	Id of the favorite address to delete

Delete an existing favorite journey

fun deleteJourney(travelId: String)

Param	Type	Description
travelId	String	Travel id of the favorite journey to delete

Delete an existing favorite POI

fun deletePoi(id: String)

Param	Type	Description
id	String	Id of the favorite POI to delete

Delete an existing favorite station

fun deleteStation(stopAreaId: String, lineId: String)

Param	Type	Description
stopAreaId	String	Navitia stop area id of the favorite station to delete
lineId	String	Navitia line id of the favorite station to delete

Data

AddressBookmark

Name	Required	Description	Type
databaseId		Unique database id	Long?
id		Unique address id	String
name		Address name	String
houseNumber		House number	Int
roadName		Address label	String
postalCode		Address postal code	String
city		Address city	String
type		Address type home, work or custom	String
additionalInformation		Free field to save extra data	String

JourneyBookmark

Name	Required	Description	Type
databaseId		Unique database id	Long?
travelId		Unique journey id	String
from		Departure name	String
fromId		Departure Navitia id	String
to		Arrival name	String
toId		Arrival Navitia id	String
sections		Array of included journey sections	List<SharedData.SectionBookmark>
isBikeSpecific		Array of connection modes. For example: ["bike", "walking"]	Boolean
additionalInformation		Free field to save extra data	String

LineBookmark

Name	Required	Description	Type
id		Navitia line id	String
code		Navitia line code	String
textColor		Navitia line text color in hex format	String
color		Navitia line color in hex format	String
commercialModeId		Navitia public transport commercial mode. Example: commercial_mode:Bus	String
commercialModeName		Navitia public transport commercial name. Example: Bus	String
physicalMode		Navitia public transport physical mode id. Example: physical_mode:Bus	String
networkId		Navitia public transport network id. Example: network:xxx:Operator_21	String
networkName		Navitia public transport network name. Example: Operator 21	String

SectionBookmark

Name	Required	Description	Type
type		Section type. Example: public_transport	String
mode		Section mode. Example: walking	String
lineId		Navitia line id	String
lineCode		Navitia line code	String
lineTextColor		Navitia line text color in HEX format	String
lineColor		Navitia line color in HEX format	String
commercialMode		Navitia public transport commercial mode. Example: commercial_mode:Bus	String
physicalMode		Navitia public transport physical mode. Example: physical_mode:Bus	String
duration		Section duration in seconds	Int

PoiBookmark

Name	Required	Description	Type
databaseId		Unique database id	Long?
id		Unique POI id	String
coords		POI coordinates	LatLng
name		POI name	String
address		POI address	AddressBookmark
type		POI type	String
typeId		Navitia POI type id. Example: poi_type:amenity:hospital	String
providerId		Navitia POI provider id	String
additionalInformation		Free field to save extra data	String

StationBookmark

Name	Required	Description	Type
databaseId		Unique database id	Long?
stopAreaId		Navitia stop area id	String
coords		Station coordinates	LatLng
name		Station name	String
lines		Station lines	List<SharedData.LineBookmark>
additionalInformation		Free field to save extra data	String

Communicating with other modules or the app

Bookmark 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 route 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)

1. appRouterDataImpl should be the class instance implementing AppRouter.Data interface. We recommend using an Application subclass.

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

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

1. appRouterUiImpl should be the class instance implementing AppRouter.UI interface. We recommend using a Application subclass.

Data interface methods

override fun onUpdateFavoriteStations(id: String) {
    // handle the favorite station update booking
}

Param	Type	Description
id	String	Updated favorite station id

Modules

Journey

Enabling

This module communicates with Journey module in order to get directions for a chosen itinerary. You should enable the go_from_go_to parameter in the features configuration.

Method

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

override fun openJourneysViaHost(
    origin: SharedData.JourneyPoint?,
    destination: SharedData.JourneyPoint?,
    showDirectlyAutoCompletion: Boolean,
    showDirectlyJourneysSearch: Boolean
) {
    // launch the journey module screen or your custom screen
}

Param	Type	Description
origin	SharedData.JourneyPoint?	Desired starting point of the journey. Optional
destination	SharedData.JourneyPoint?	Desired endpoint of the journey. Optional
showDirectlyAutoCompletion	Boolean	Directly displays the search for the starting point and/or endpoint. If true, showDirectlyJourneysSearch can only be false
showDirectlyJourneysSearch	Boolean	Directly displays the journey search. If true, showDirectlyAutoCompletion can only be false

Theming

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>

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