================
iOS Trip feature
================

Our SDK can manage for you the notion of trip, giving you useful data like traveled distance or the start time of the user's last ongoing stop.

Get the SDK instance
====================

The trip feature is available through 2 protocols, you must chose the one that you prefer.

LRSafeRiderDelegationProtocol
-----------------------------

.. code-block:: swift
	:class: no-copybutton

	protocol LRSafeRiderDelegationProtocol: LRSafeRiderProtocol {

	    var tripStatusDelegate: LRTripStatusDelegate?

	    func startTrip(for vehicleType: LRVehicleType) -> LRTripStatus?
	    func stopTrip()
	}

You can get this protocol as explained below

.. code-block:: swift

	var safeRiderInstance = LRSafeRider.getShared(LRSafeRiderDelegationProtocol.self)!

The delegation protocol comes with one delegate that helps you to know what happens.

.. code-block:: swift

	protocol LRTripStatusDelegate {

	    func onTripStatusChanged(_ tripStatus: LRTripStatus)
	    func onTripStatusError(_ error: LRSafeRiderError?)
	}

The :code:`LRTripStatusDelegate` allows you to be notified of changes during a trip for a given vehicle type or the possible :ref:`SDK errors <developer-reference:Errors>`.

LRSafeRiderReactiveProtocol
---------------------------

.. code-block:: swift
	:class: no-copybutton

	protocol LRSafeRiderReactiveProtocol: LRSafeRiderProtocol {

	    var tripStatusPublisher: AnyPublisher<LRTripStatus, Never> { get }
	    var tripStatusErrorPublisher: AnyPublisher<LRSafeRiderError, Never> { get }

	    func startTrip(for vehicleType: LRVehicleType) -> LRTripStatus?
	    func stopTrip()
	}


You can get this protocol as explained below

.. code-block:: swift

	var safeRiderInstance = LRSafeRider.getShared(LRSafeRiderReactiveProtocol.self)!


The reactive protocol provides basically the same services than the delegation one but exposing Combine publishers.


Manage a trip
=============

Trip status
-----------

.. code-block:: swift
	:class: no-copybutton

	struct LRTripStatus {

	    var tripStartTime: Date
	    var distanceMeter: CLLocationDistance
	    var dwellStartTime: Date?
	}

The :code:`LRTripStatus` gives you useful data about an ongoing trip:

* :code:`tripStartTime` gives you the start time ot the trip
* :code:`distanceMeter` gives you the total traveled distance in meter from :code:`tripStartTime`
* :code:`dwellStartTime` gives you the start time of the user's last ongoing stop. If :code:`nil`, user is currently moving.


Start a trip
------------

After having initialized the SDK, you can start a trip for a given vehicle type.

.. code-block:: swift

	self.safeRiderInstance.startTrip(for: .bicycle)


This will start a continuous service to monitor a trip for the given vehicle type.

Stop a trip
-----------

After having initialized the SDK and start a trip for a given vehicle type, you can stop it.

.. code-block:: swift

	self.safeRiderInstance.stopTrip()

Listen to the trip status
-------------------------

In order to be notified of a data change during a trip for a given vehicle type, you have to do, considering the relative SafeRider protocol you are using.

Using the LRSaferiderDelegationProtocol
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: swift

	self.safeRiderInstance.tripStatusDelegate = self

	extension MyClass: LRTripStatusDelegate {

	    func onTripStatusChanged(_ tripStatus: LRTripStatus) {
	        log.debug("new trip status: \(tripStatus)")
	    }

	    func onTripStatusError(_ error: LRSafeRiderError?) {
	        log.error("trip status error: \(error.localizedDescription)")
	    }
	}

Using the LRSaferiderReactiveProtocol
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: swift

	var cancellableBag = Set<AnyCancellable>()

	self.safeRiderInstance.tripStatusPublisher
        .sink { tripStatus in
            log.debug("new trip status: \(tripStatus)")
        }
        .store(in: &self.cancellableBag)

	self.safeRiderInstance.tripStatusErrorPublisher
	    .sink { error in
	        guard let error else { return }
	            log.error("trip status error: \(error.localizedDescription)")
	        }
	    .store(in: &self.cancellableBag)