Android PortalApiBase framework

PortalApiBase SDK Documentation - v1.2.6 (27 Jun, 2025)

This document describes how ScopeTechnology framework "PortalApiBase" works and how to integrate into your application. While the target audience is coders/developers, it brings better understanding for those who are not too tech-savvy as well.

PortalApiBase framework main functionality is to provide an interface to backend wrapping up all necessary APIs.

1. Driving behaviour events filtering

It's possible to filter the following events: acceleration, breaking and cornering. It means that all the events whose have gforce value lower than defined in Tenant Settings (see Connected Cars Portal -> Tenant Settings > Group 16: Driver Behaviour) are filtered out.

1.1. Trips API

Using

BasePortalApi.getTrips(from: DateTime, to: DateTime, withEvents: Bool)

events are already filtered out.

1.2. Get acceleration thresholds from Portal

To use the same thresholds as ConnectedCar portal does first you need to request it and cache. Using

BasePortalApi.getTenantSettingValues(ExceptionThresholdsTenantSettings.getTenantSettingsKeys()).let { thresholdResponse ->
    if (thresholdResponse.isSuccessful) {
        thresholdResponse.result?.let { result ->
            val thresholds = ExceptionThresholdsTenantSettings.getExceptionThresholds(result)
            thresholds.storeExceptionThresholdsTenantSettings()
        }
    }
}

1.3. MZone Events API

Using

BasePortalApi.getMZoneEvents(startDate: String, endDate: String, vehicleId: String)

filtering is handled by the app using the following functions:

    private fun getMZoneEvents() {
        val endDate = DateTime.now()
        val startDate = endDate.minusDays(1).withTimeAtStartOfDay()

        lifecycleScope.launch {
            val mZoneVehicleId = BasePortalApi.getLiveSelectedVehicle().value?.mZoneVehicleId ?: ""
            val tripStartTime = startDate.toString(Constants.ISO_8601_DATE_FORMAT)
            val tripEndTime = endDate.toString(Constants.ISO_8601_DATE_FORMAT)

            BasePortalApi.getMZoneEvents(tripStartTime, tripEndTime, mZoneVehicleId).result?.let {
                val filteredEvents = filterEventsByThreshold(it.value)
            }
        }
    }

    private fun filterEventsByThreshold(events: List<MZoneDetailedTrip>): List<MZoneDetailedTrip> {
        val result = arrayListOf<MZoneDetailedTrip>()
        if (events.isNotEmpty()) {
            val thresholds = ExceptionThresholdsTenantSettings.fromPrefUtil()
            events.forEach { mZoneDetailedTrip ->
                when (mZoneDetailedTrip.eventTypeDescription) {
                    EventType.DriverBehaviourAcceleration.eventName -> {
                        if (mZoneDetailedTrip.getExceptionGForce() >= (thresholds?.accelerationThreshold ?: 0.0f)) {
                            result.add(mZoneDetailedTrip)
                        } else {
                            Timber.i("Filtered low GForce Acceleration event: ${mZoneDetailedTrip.getExceptionGForce()}")
                        }
                    }
                    EventType.DriverBehaviourExcessiveBraking.eventName -> {
                        if (mZoneDetailedTrip.getExceptionGForce() >= (thresholds?.brakingThreshold ?: 0.0f)) {
                            result.add(mZoneDetailedTrip)
                        } else {
                            Timber.i("Filtered low GForce Braking event: ${mZoneDetailedTrip.getExceptionGForce()}")
                        }
                    }
                    EventType.DriverBehaviourCornering.eventName -> {
                        if (mZoneDetailedTrip.getExceptionGForce() >= (thresholds?.corneringThreshold ?: 0.0f)) {
                            result.add(mZoneDetailedTrip)
                        } else {
                            Timber.i("Filtered low GForce Cornering event: ${mZoneDetailedTrip.getExceptionGForce()}")
                        }
                    }
                    else -> {
                        result.add(mZoneDetailedTrip)
                    }
                }

            }
        }
        return result
    }