Package com.sentilant.telematicssdk

Interface TelematicsSDKInterface

All Known Implementing Classes:
TelematicsSDK
public interface TelematicsSDKInterface
Interface defining the methods for the Telematics SDK. This interface provides methods for initializing the SDK, managing user and vehicle data, starting and stopping the telematics service, handling permissions, and reporting vehicle data.

  • Method Details

    • initSDK

      void initSDK(String clientId, String clientSecret, boolean isStaging, TelematicsCallback callback)
      Initializes the Telematics SDK with the provided credentials and environment.
      Parameters:
      clientId - The client ID provided for authentication.
      clientSecret - The client secret provided for authentication.
      isStaging - true to use the staging environment; false to use the production environment.
      callback - The callback to handle the success or failure of the initialization process.

    • initSDK

      void initSDK(String client, String clientId, String clientSecret, boolean isStaging, TelematicsCallback callback)
      Initializes the Telematics SDK with the provided credentials and environment.
      Parameters:
      client - The client name provided for authentication.
      clientId - The client ID provided for authentication.
      clientSecret - The client secret provided for authentication.
      isStaging - true to use the staging environment; false to use the production environment.
      callback - The callback to handle the success or failure of the initialization process.

    • getFuelTypes

      void getFuelTypes(FuelTypesCallback callback)
      Asynchronously retrieves a map of fuel types supported by the SDK.

      The resulting map, where each key is the fuel type name and the corresponding value is its identifier code, is delivered via the provided FuelTypesCallback.

      Parameters:
      callback - the callback that will receive the fuel types map on success or an error if retrieval fails.

    • getVehicleTypes

      void getVehicleTypes(VehicleTypesCallback callback)
      Asynchronously retrieves a map of vehicle types supported by the SDK.

      The resulting map, where each key is the vehicle type name and the corresponding value is its identifier code, is delivered via the provided VehicleTypesCallback.

      Parameters:
      callback - the callback that will receive the vehicle types map on success or an error if retrieval fails.

    • getAddVehicleReasons

      void getAddVehicleReasons(AddVehicleReasonsCallback callback)
      Asynchronously retrieves a map of vehicle add reasons supported by the SDK.

      The resulting map, where each key is the vehicle add reason name and the corresponding value is its identifier code, is delivered via the provided AddVehicleReasonsCallback.

      Parameters:
      callback - the callback that will receive the vehicle add reasons map on success or an error if retrieval fails.

    • getRequiredPermissions

      String[] getRequiredPermissions()
      Returns an array of Android permissions required by the SDK to function correctly.
      Returns:
      An array of required permission strings (e.g., android.Manifest.permission.ACCESS_FINE_LOCATION).

    • checkPermissions

      List<String> checkPermissions()
      Checks the current permissions and returns a list of permissions that are not granted.
      Returns:
      A list of missing permission strings that are required by the SDK but not granted.

    • login

      void login(String id, String extraID, String group, String serviceId, TelematicsCallback callback)
      Logs in a user with the provided credentials and group information.
      Parameters:
      id - The unique identifier for the user.
      extraID - An additional user identifier, if applicable.
      group - The group code or name the user belongs to.
      serviceId - The service ID associated with the user.
      callback - The callback to handle the success or failure of the login process.

    • setVehicle

      void setVehicle(String plate, String internalPlate, int type, int addReason, int fuelType, TelematicsCallback callback)
      Sets the vehicle information with the specified details.
      Parameters:
      plate - The vehicle's license plate number.
      internalPlate - An internal identifier or secondary plate for the vehicle.
      type - The vehicle type identifier code (as returned by getVehicleTypes(VehicleTypesCallback)).
      addReason - The reason identifier code for adding the vehicle (as returned by getAddVehicleReasons(AddVehicleReasonsCallback)).
      fuelType - The fuel type identifier code (as returned by getFuelTypes(FuelTypesCallback)).
      callback - The callback to handle the success or failure of setting the vehicle information.

    • setVehicle

      void setVehicle(String plate, TelematicsVehicleDetailsCallback callback)
      Sets the current vehicle by its license plate.

      This method attempts to retrieve the vehicle associated with the provided license plate. If the vehicle exists, its details will be returned through the given callback. If the vehicle is not found, the callback will receive an appropriate error.

      Parameters:
      plate - The license plate number of the vehicle to be set.
      callback - The callback used to return the vehicle details if found, or an error if not.

    • getCurrentVehicleInfo

      void getCurrentVehicleInfo(TelematicsVehicleDetailsCallback callback)
      Retrieves the details of the currently selected vehicle.

      The current vehicle information is provided asynchronously through the supplied callback. If no vehicle has been set, the callback will return an error.

      Parameters:
      callback - The callback used to return the current vehicle details or an error if unavailable.

    • clearVehicle

      void clearVehicle()
      Clears the current vehicle information from the SDK.

    • setServiceCode

      void setServiceCode(String serviceCode, TelematicsCallback callback)
      Sets the service code for the telematics service.
      Parameters:
      serviceCode - The service code to be used by the telematics service.
      callback - The callback to handle the success or failure of setting the service code.

    • isTelematicsServiceRunning

      boolean isTelematicsServiceRunning()
      Checks if the telematics service is currently running.
      Returns:
      true if the telematics service is running; false otherwise.

    • logout

      void logout()
      Logs out the current user and stops the telematics service.

    • getCurrentVehicleInfo

      void getCurrentVehicleInfo(TelematicsVehicleCallback callback)
      Retrieves the current vehicle information and provides it via the callback.
      Parameters:
      callback - The callback to receive the current vehicle information.

    • getCurrentUserInfo

      void getCurrentUserInfo(TelematicsUserCallback callback)
      Retrieves the current user information and provides it via the callback.
      Parameters:
      callback - The callback to receive the current user information.

    • getCurrentUserInfo

      void getCurrentUserInfo(TelematicsUserDetailsCallback callback)
      Retrieves the current telematics user information and provides it asynchronously via the given TelematicsUserDetailsCallback.

      Use this variant when you need access to the full TelematicsUserDetails object, including fields such as id, name, group, and nickname.

      Parameters:
      callback - the callback that will receive the detailed user information or an error if the retrieval fails

    • startTelematicsService

      void startTelematicsService(String reason, String observations, TelematicsCallback callback)
      Starts the telematics service if the required user and vehicle information is available.

      This method validates that all necessary user and vehicle details are provided before initiating the telematics service. It logs the specified reason and any additional observations for auditing or troubleshooting purposes. The provided callback is then used to notify the caller whether the service was successfully started or if an error occurred.

      Parameters:
      reason - the reason for starting the telematics service, used for logging or auditing purposes; can be null or empty.
      observations - additional observations or comments related to starting the telematics service; may be an empty string if no extra information is available.
      callback - the callback to handle the success or failure of starting the telematics service;

    • startTelematicsService

      void startTelematicsService(TelematicsServiceOptions options, TelematicsCallback callback)
      Starts the telematics service with the specified options.

      This method allows providing a TelematicsServiceOptions instance to configure the behavior of the telematics service startup. The callback is used to notify whether the service was successfully started or if an error occurred.

      Parameters:
      options - the options to configure how the telematics service should be started; must not be null.
      callback - the callback to handle the success or failure of starting the telematics service; must not be null.

    • stopTelematicsService

      void stopTelematicsService(TelematicsCallback callback)
      Stops the telematics service.
      Parameters:
      callback - The callback to handle the success or failure of stopping the telematics service.

    • stopTelematicsService

      void stopTelematicsService(TelematicsServiceOptions options, TelematicsCallback callback)
      Stops the telematics service with the specified options.

      This method allows providing a TelematicsServiceOptions instance to configure the behavior of the telematics service shutdown. The callback is used to notify whether the service was successfully stopped or if an error occurred.

      Parameters:
      options - the options to configure how the telematics service should be stopped; must not be null.
      callback - the callback to handle the success or failure of stopping the telematics service; must not be null.

    • reportKilometers

      void reportKilometers(int kilometers, String observations, TelematicsCallback callback)
      Reports the current odometer reading for the vehicle.
      Parameters:
      kilometers - The current odometer reading in kilometers.
      observations - Any observations or comments to include with the report.
      callback - The callback to handle the success or failure of the reporting operation.

    • correctKilometers

      void correctKilometers(int kilometers, String observations, int correctionCount, TelematicsCallback callback)
      Corrects the odometer reading for the vehicle by applying the given value to a specified number of past records.
      Parameters:
      kilometers - The corrected odometer reading in kilometers.
      observations - Any observations or comments related to the correction.
      correctionCount - The number of past records to which the correction should be applied.
      callback - The callback to handle the success or failure of the correction operation.

    • isBatteryOptimizationDeactivated

      boolean isBatteryOptimizationDeactivated()
      Checks if battery optimization is disabled for the application, which is required for accurate tracking.
      Returns:
      true if battery optimization is disabled for the app; false otherwise.

    • getEstimatedMileage

      double getEstimatedMileage()
      Retrieves the estimated current mileage for the vehicle in kilometers.

      This method returns the estimated mileage based on the data collected by the telematics service. If the telematics service is not running or insufficient data is available, it will return -1 to indicate that mileage estimation is not possible.

      Returns:
      The estimated mileage in kilometers as a double; returns -1 if estimation is not possible.

    • getTrip

      void getTrip(long id, TelematicsTripCallback callback)
      Retrieves the details of a specific trip by its unique ID.
      Parameters:
      id - The unique identifier of the trip you want to retrieve.
      callback - The callback interface to handle the response. - If successful, the TelematicsTripCallback.onTelematicsTripFetched(TelematicsTripDetail) method will be called with the trip details. - If there is an error, the TelematicsTripCallback.onError(TelematicsSDKException) method will be called with the error information.

    • getTrips

      void getTrips(String startDate, String endDate, TelematicsTripsCallback callback)
      Retrieves a list of trips within the specified date range.
      Parameters:
      startDate - The start date for filtering trips in the format "YYYY-MM-DDTHH:mm:ssZ" (ISO 8601 with timezone).
      endDate - The end date for filtering trips in the format "YYYY-MM-DDTHH:mm:ssZ" (ISO 8601 with timezone).
      callback - The callback interface to handle the response. - If successful, the TelematicsTripsCallback.onTelematicsTripsFetched(List<TelematicsTripResume>) method will be called with the list of trips. - If there is an error, the TelematicsTripsCallback.onError(TelematicsSDKException) method will be called with the error information.

    • getFormTemplateByReference

      void getFormTemplateByReference(String reference, TelematicsFormTemplateCallback callback)
      Retrieves a form template by its reference.
      Parameters:
      reference - The unique reference identifier for the form template.
      callback - The callback to handle the form template retrieval.

    • getRequiredFormTemplates

      void getRequiredFormTemplates(TelematicsFormTemplateCallback callback)
      Retrieves a list of required form templates.
      Parameters:
      callback - The callback to handle the retrieval of required form templates.

    • saveFormTemplates

      void saveFormTemplates(List<TelematicsFormTemplateItemResponse> telematicsFormTemplateItemResponses, TelematicsCallback callback)
      Saves the responses to form templates.
      Parameters:
      telematicsFormTemplateItemResponses - A list of form template item responses to be saved.
      callback - The callback to handle the success or failure of the save operation.

    • getMetricsSummary

      void getMetricsSummary(String startDate, String endDate, TelematicsMetricsSummaryCallback callback)
      Retrieves a summary of metrics for the specified date range.
      Parameters:
      startDate - The start date for retrieving metrics in the format "YYYY-MM-DDTHH:mm:ssZ" (ISO 8601 with timezone).
      endDate - The end date for retrieving metrics in the format "YYYY-MM-DDTHH:mm:ssZ" (ISO 8601 with timezone).
      callback - The callback to handle the metrics summary retrieval.

    • getLastTelematicsPeriodMetricsSummary

      void getLastTelematicsPeriodMetricsSummary(TelematicsMetricsSummaryCallback callback)

    • getLastTelematicsDayMetricsSummary

      void getLastTelematicsDayMetricsSummary(TelematicsMetricsSummaryCallback callback)

    • getChallenges

      void getChallenges(boolean isGroupChallenges, TelematicsChallengesCallback callback)

    • getChallengeMetrics

      void getChallengeMetrics(int challengeId, TelematicsChallengeMetricsCallback callback)

    • getChallengeGroupsRanking

      void getChallengeGroupsRanking(int challengeId, TelematicsChallengeGroupsRankingCallback callback)

    • insertManualEvent

      void insertManualEvent(TelematicsManualEventType eventType)