===================
Android Quick Start
===================

Requirements
============
The SafeRider SDK requires Android 5.0 or higher (API level 21). It is optimized for phones, not tablets. If these requirements are too limiting for you, contact us.

Installation
============
The SafeRider SDK for Android is available via Maven and can be added to your project via Gradle. Add the following code to your :code:`settings.gradle` in :code:`dependencyResolutionManagement`:

.. code-block:: groovy
	
	dependencyResolutionManagement {
	   repositories {
	       google()
	       mavenCentral()

	       maven {
	           name = "SafeRider"
	           url = uri("https://maven.pkg.github.com/liberty-rider/saferider-android-distribution/")
	           credentials {
	               username = "liberty-ops"
	               password = "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"
	           }
	       }
	   }
	}

Inside the dependencies of the :code:`build.gradle` of your app module, use the following code:

.. code-block:: groovy

	dependencies {
	    ...
	    implementation "com.libertyrider:saferider-android:0.9.3"
	}

You may have to add these lines under the “android” block of the same :code:`build.gradle` file:

.. code-block:: groovy

	android {
	    ...
	    packagingOptions {
	        resources.excludes.add("META-INF/*")
	    }
	}

The SafeRider SDK will automatically add the following permissions to your app manifest. You are responsible for requesting these permissions at run time if needed.


.. code-block:: java

	android.permission.ACCESS_FINE_LOCATION
	android.permission.ACCESS_BACKGROUND_LOCATION // Unused below Android 10 (API level 29).
	android.permission.ACCESS_COARSE_LOCATION // Automatically granted, no user prompt is needed.
	android.permission.FOREGROUND_SERVICE // Automatically granted, no user prompt is needed.
	android.permission.INTERNET // Automatically granted, no user prompt is needed.

Initialization
==============

You need to initialize the SDK by setting your API key.

You should only initialize the SafeRider once in your application, during app startup.
The same SDK instance will then be shared throughout your app by accessing a singleton.
The static call to :code:`initialize()` must happen during your :code:`Application.onCreate()` so that the protection can continue in the event of your app being killed then restarted by the OS.
You can also set your rectangular logo (.png/.jpeg or .xml) for being displayed on all accident workflow screens.

.. code-block:: kotlin

	class YourApplication : Application() {
	   override fun onCreate() {
	       super.onCreate()

	       SafeRider.initialize(applicationContext, 
		   apiKey = "your-api-key-here",
		   accidentUiScreenLogo = R.drawable.your_rectangular_logo)
	   }
	}

Start a Protection Session
==========================

After SDK initialization, you can start a protection session by calling :code:`startProtection()` as shown below. For details about each parameter, look at the :doc:`Android Reference <developer-reference>`.
This will start continuous processing to analyze sensor data and detect accidents.
Only one session can be active on a device at a given time.
Before calling :code:`startProtection()`, you must ensure that the :doc:`required permissions <android-background-policies>` have been granted ; otherwise the SDK will throw an error.

.. code-block:: kotlin

	fun onStartButtonClick() {
	    SafeRider.sharedInstance.startProtection(vehicleType = LRVehicleType.MOTORCYCLE,
	                    userId = "00000000-0000-0000",
	                    phoneNumber = "+33600000000",
	                    firstName = "John",
	                    lastName = "DOE",
	                    metadata = hashMapOf("trip_id" to "00000-0000-0000-0001", "autostart" to false);
	}

When you want to end the protection session and sensor processing, call :code:`stopProtection()`.

Listen to the SDK Protection Status
===================================

In order for your app to interact with the SDK lifecycle, you need to listen to SDK :ref:`status change events <developer-reference:Protection Status Updates>`. Here is how:

.. code-block:: kotlin

	SafeRider.sharedInstance.addProtectionStatusListener(object : SafeRider.ProtectionStatusListener {
	    override fun onStatusChanged(status: LRProtectionStatus) {
	        Log.d(
	            TAG, "New status: isActive: ${status.isProtectionActive}," +
	                            " sessionId: ${status.sessionId}," +
	                            " hasAlert: ${status.alert != null}," +
	                            " hasEmergency: ${status.emergency != null}"
	        )
	        status.alert?.let { // alert != null
	            Log.d(
	                TAG, "Ongoing Alert Countdown: start time: ${it.alertStartTime}," +
	                                             " duration: ${it.alertDuration}"
	            )
	        }
	        status.emergency?.let { // emergency != null
	            Log.d(
	                TAG, "Ongoing Emergency: id: ${it.emergencyId}," +
	                                       " sending: ${it.isEmergencySending}," +
	                                       " sending failed: ${it.hasEmergencySendingFailed}," +
	                                       " sent: ${it.isEmergencySent}," +
	                                       " canceled: ${it.isEmergencyCanceled}," +
	                                       " ended: ${it.isEmergencyEnded}"
	            )
	        }
	    }
	}