Bookmark iOS

Setup

In your project, add the following lines to your Podfile:

source 'https://github.com/CocoaPods/Specs.git' # Default Cocoapods URL
source 'https://github.com/hove-io/Podspecs.git' # Bookmark podspec URL

target 'YOUR_PROJECT_SCHEME' do
  pod 'BookmarkSDK', '1.9.3' # Bookmark Pod definition
end

# Required for XCFramework
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

Using your CLI, run pod install in your project directory.

Implementation

Warning

Make sure to read the modules configuration section before proceeding

This module is set up by calling Bookmark.shared.initialize() method which takes the following parameters:

Name	Description	Type	Example
`coverage`	Navitia coverage	`String`	`fr-idf`
`token`	Get your token	`String`
`env`	Navitia environment	`String`	`PROD`
`colors`	Define the custom colors	`AroundMeColorsConfiguration`	-
`fonts`	Use custom fonts	`AroundMeFontsConfiguration`	-
`lineResources`	List of transport lines resource IDs	`[LineResource]`	-
`modeResources`	List of transport modes resource IDs	`[ModeResource]`	-
`transportCategories`	List of supported transport modes	`[TransportCategory]`	-

You can also call the initialize() method with the global JSON configuration file added to your application bundle:

Name	Required	Description	Type	Example
`token`		Get your token	`String`
`configurationJsonFile`		Global configuration JSON file name	`String`	`configuration.json`

Example

Configuration with fileManual configuration

do {
    try Bookmark.shared.initialize(
        token: "your_token", 
        configurationJsonFile: "aroundme_configuration.json"
    )                                                               
} catch {
    Logger.error("%@", String(
        format: "Bookmark SDK cannot be initialized! %@", 
        error.localizedDescription
    ))
}

do {
    let transportCategories = [TransportCategory(
        modules: ["aroundme"],
        iconRes: "ic_section_mode_metro",
        nameRes: "metro",
        selected: true, 
        modes: [TransportCategoryMode(
            physical: TransportPhysicalMode(
                id: "physical_mode:Metro", 
                nameRes: "metro"
            ),
            commercial: TransportCommercialMode(
                id: "commercial_mode:Metro", 
                name: "Metro"
            )
        )],
        firstSectionModes: ["walking"],
        lastSectionModes: ["walking"]
    )]

    let bookmarkColorsConfiguration = AroundMeColorsConfiguration(
        primaryColor: "#88819f", 
        secondaryColor: "#8faa96"
    )

    try Bookmark.shared.initialize(
        coverage: "fr-idf",
        token: "your_token",
        env: "PROD",
        colors: bookmarkColorsConfiguration,
        transportCategories: transportCategories
    )                                                                  
} catch {
    Logger.error("%@", String(
        format: "Bookmark SDK cannot be initialized! %@", 
        error.localizedDescription
    ))
}

Events tracking

In order to receive the list of generated events within Bookmark module, you have to assign the instance of the tracker to the Bookmark module instance as follows and implement the required methods:

Bookmark.shared.tracker = self

Launching

This module has a single entry point. The parameter showBack handles the back button visibility on the first screen.

guard let bookmarkViewController = Bookmark.shared.rootViewController else {
    return nil
}
bookmarkViewController.showBack = false // Hide back button embedded in the first screen

If you want to use the rootViewController as a ChildViewController of your ViewController, you should embed it in an NavigationController.

Using a NavigationControllerUsing a ChildViewController

navigationController?.pushViewController(
    bookmarkViewController, 
    animated: false
)

yourViewController.addChild(UINavigationController(
    rootViewController: bookmarkViewController
))

Manipulating data

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

Methods

The various CRD methods are accessed through BookmarkUI.shared.

Create

Create a new favorite address. Returns a boolean if the creation has succeeded or not.

func addFavoriteAddress(_ address: SharedData.FavoriteAddress) -> Bool

Param	Type	Description
`address`	`SharedData.FavoriteAddress`	Favorite address to create

Create a new favorite journey. Returns a boolean if the creation has succeeded or not.

func addFavoriteJourney(_ journey: SharedData.FavoriteJourney) -> Bool

Param	Type	Description
`journey`	`SharedData.FavoriteJourney`	Favorite journey to create

Create a new favorite POI. Returns a boolean if the creation has succeeded or not.

func addFavoritePoi(_ poi: SharedData.FavoritePoi) -> Bool

Param	Type	Description
`poi`	`SharedData.FavoritePoi`	Favorite POI to create

Create a new favorite station. Returns a boolean if the creation has succeeded or not.

func addFavoriteStation(_ station: SharedData.FavoriteStation) -> Bool

Param	Type	Description
`station`	`SharedData.FavoriteStation`	Favorite station to create

Read

Fetch a favorite address data. Returns SharedData.FavoriteAddress or nil if not found.

func fetchFavoriteAddress(id: String) -> SharedData.FavoriteAddress?

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

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

func fetchFavoriteAddresses(max: Int) -> [SharedData.FavoriteAddress]

Param	Type	Description
`max`	`Int`	Limit the result count. `0` for all data

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

func fetchFavoriteJourneys(max: Int) -> [SharedData.FavoriteJourney]

Param	Type	Description
`max`	`Int`	Limit the result count. `0` for all data

Get if a journey is added to favorites. Returns a boolean if the creation has succeeded or not.

func isJourneyInBookmark(journeyId: String) -> Bool

Param	Type	Description
`journeyId`	`String`	Id of the favorite journey to check

Fetch a favorite POI data. Returns SharedData.FavoritePoi or nil if not found.

func fetchFavoritePoi(id: String) -> SharedData.FavoritePoi?

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

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

func fetchFavoritePois(max: Int) -> [SharedData.FavoritePoi]

Param	Type	Description
`max`	`Int`	Limit the result count. `0` for all data

Fetch a favorite station data. Returns SharedData.FavoriteStation or nil if not found.

func fetchFavoriteStation(stopAreaId: String, lineId: String) -> SharedData.FavoriteStation?

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.FavoriteStation or an empty list if there is no data.

func fetchFavoriteStations(max: Int) -> [SharedData.FavoriteStation]

Param	Type	Description
`max`	`Int`	Limit the result count. `0` for all data

Update

v Update an existing favorite address. Returns a boolean if the update has succeeded or not.

func updateFavoriteAddress(updatedAddress: SharedData.FavoriteAddress) -> Bool

v Update an existing favorite POI. Returns a boolean if the creation has succeeded or not.

func updateFavoritePoi(updatedPoi: SharedData.FavoritePoi) -> Bool

v Update an existing favorite station. Returns a boolean if the update has succeeded or not.

func updateFavoriteStation(updatedStation: SharedData.FavoriteStation) -> Bool

v Update an existing favorite journey. Returns a boolean if the update has succeeded or not.

func updateFavoriteJourney(updatedJourney: SharedData.FavoriteJourney) -> Bool

Delete

v Delete an existing favorite address. Returns a boolean if the creation has succeeded or not.

func deleteFavoriteAddress(id: String) -> Bool

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

Delete an existing favorite journey. Returns a boolean if the creation has succeeded or not.

func deleteFavoriteJourney(id: String) -> Bool

Param	Type	Description
`id`	`String`	Id of the favorite journey to delete

Delete an existing favorite POI. Returns a boolean if the creation has succeeded or not.

func deleteFavoritePoi(id: String) -> Bool

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

Delete an existing favorite station. Returns a boolean if the creation has succeeded or not.

func deleteFavoriteStation(id: String) -> Bool

Param	Type	Description
`id`	`String`	Id of the favorite station to delete

Data

`FavoriteAddress`

Name	Description	Type
`uuid`	Unique database address id	`String`
`navitiaId`	Unique navitia id	`String`
`name`	Address name	`String`
`houseNumber`	House number	`Int`
`address`	Address label	`String`
`city`	Address city	`String`
`zipCode`	Address postal code	`String`
`addressTypeId`	Address type `home`, `work` or `custom`	`String`
`additionalInformation`	Free field to save extra data	`String`

`FavoriteJourney`

Name	Description	Type
`uuid`	Unique database journey id	`String`
`journeyId`	Unique journey id	`String`
`fromName`	Departure name	`String`
`fromId`	Departure Navitia id	`String`
`toName`	Arrival name	`String`
`toId`	Arrival Navitia id	`String`
`connectionModes`	Array of connection modes. For example: `["bike", "walking"]`	`[String]`
`sections`	Array of included journey sections	`[SharedData.FavoriteJourneySection]`
`additionalInformation`	Free field to save extra data	`String`

`FavoriteJourneySection`

Name	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`

`FavoritePoi`

Name	Description	Type
`uuid`	Unique database POI id	`String`
`navitiaId`	Unique POI id	`String`
`coords`	POI coordinates	`CLLocationCoordinate2D`
`name`	POI name	`String`
`address`	POI address	`String`
`type`	POI type	`String`
`typeId`	Navitia POI type ID. Example: `poi_type:amenity:hospital`	`String`
`network`	Navitia POI network	`String`
`additionalInformation`	Free field to save extra data	`String`

`FavoriteStation`

Name	Description	Type
`uuid`	Unique database station id	`String`
`stopAreaId`	Navitia stop area id	`String`
`coords`	Station coordinates	`CLLocationCoordinate2D`
`name`	Station name	`String`
`lineId`	Navitia line id	`String`
`lineCode`	Line code	`String`
`lineColor`	Line color in HEX format	`String`
`lineTextColor`	Line text 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`
`additionalInformation`	Free field to save extra data	`String`

Communicating with other modules

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

try Router.shared
    .register(aroundMe: Bookmark.shared.bookmarkRouter)
    ... // Register modules and/or app
    .initialize()

Modules

Journey

Enabling

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

Journey module must also be registered in the Router to build the connection between these modules:

Router.shared.register(journey: JourneySdk.shared.journeyRouter)