Smart 1 Android SDK

Smart1 SDK is a comprehensive Android library for logistics and fleet management operations. It provides modules for authentication, user management, order tracking, route planning, and real-time location tracking.

Installation

Gradle (Groovy DSL)

1. Add Repository

Add the Maven repository to your build.gradle:

repositories {
    maven {
        url 'https://git.sitimapa.co/api/v4/projects/1926/packages/maven'
        credentials {
            username = "your-username"
            password = "your-private-token"
        }
    }
}

2. Add Dependency

dependencies {
    implementation 'com.servinformacion.smart1sdk:smart1-sdk:1.0.0'
}

Gradle (Kotlin DSL)

1. Add Repository

Add the Maven repository to your build.gradle.kts:

repositories {
    maven("https://git.sitimapa.co/api/v4/projects/1926/packages/maven") {
        credentials {
            username = "your-username"
            password = "your-private-token"
        }
    }
}

2. Add Dependency

dependencies {
    implementation("com.servinformacion.smart1sdk:smart1-sdk:1.0.0")
}

Maven

1. Add Repository Configuration

Add the following repository configuration to your pom.xml:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://git.sitimapa.co/api/v4/projects/1926/packages/maven</url>
  </repository>
</repositories>

<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://git.sitimapa.co/api/v4/projects/1926/packages/maven</url>
  </repository>

  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://git.sitimapa.co/api/v4/projects/1926/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

2. Add Credentials

Configure your credentials in ~/.m2/settings.xml:

<servers>
  <server>
    <id>gitlab-maven</id>
    <configuration>
      <httpHeaders>
        <property>
          <name>Private-Token</name>
          <value>YOUR_PRIVATE_TOKEN</value>
        </property>
      </httpHeaders>
    </configuration>
  </server>
</servers>

3. Add Dependency

Add the SDK dependency to your pom.xml:

<dependency>
  <groupId>com.servinformacion.smart1sdk</groupId>
  <artifactId>smart1-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Getting Started

Initialize the SDK

The SDK must be initialized in your Application class before using any of its features.

1. Create or Update Your Application Class

Basic Initialization:

import android.app.Application
import com.servinformacion.smart1sdk.android.init_config.Smart1SDK

class MyApplication : Application() {
    
    override fun onCreate() {
        super.onCreate()
        
        // Initialize Smart1 SDK
        Smart1SDK.initialize(this)
    }
}

Advanced Initialization (with your own Koin modules):

import android.app.Application
import com.servinformacion.smart1sdk.android.init_config.Smart1SDK
import org.koin.core.logger.Level

class MyApplication : Application() {
    
    override fun onCreate() {
        super.onCreate()
        
        // Initialize SDK with your app modules
        Smart1SDK.initialize(
            context = this,
            addKoinAndroidLogger = true,
            koinAndroidLoggerLevel = Level.DEBUG,
            extraKoinModules = listOf(
                myAppModule,
                viewModelModule
            )
        )
    }
}

⚠️ Important: Do NOT call startKoin { } anywhere in your app. The SDK handles Koin initialization internally when you call Smart1SDK.initialize(). If you try to call startKoin() yourself, Koin will throw a KoinAppAlreadyStartedException error.

2. Register Application in AndroidManifest.xml

<application
    android:name=".MyApplication"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
    
    <!-- Your activities -->
    
</application>

Configure SDK Session

Before using any SDK module (except core), you must configure a session using InitSDKConfig.

import com.servinformacion.smart1sdk.android.init_config.InitSDKConfig
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class MainActivity : AppCompatActivity() {
    
    private val initSDKConfig = InitSDKConfig()
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        initializeSDKSession()
    }
    
    private fun initializeSDKSession() {
        // Check if SDK is already initialized
        if (initSDKConfig.isInitialized()) {
            println("SDK already initialized, proceeding...")
            // SDK is ready to use
            return
        }
        
        val result = initSDKConfig.init(
            sdkApiKey = "your-sdk-api-key",
            email = "user@example.com"  
        )
        
        when (result) {
            is ResultS1SDK.Success -> {
                println("SDK session initialized successfully")
                // Now you can use other SDK modules
            }
            is ResultS1SDK.Error -> {
                println("Failed to initialize SDK session: ${result.error}")
            }
        }
    }
}

Important Notes:

The sdkApiKey is required and must be provided by Servinformacion.
You can provide either email or phoneNumber (at least one is required).
This initialization creates a session that allows access to all SDK modules.
The same sdkApiKey can be used for user registration (RegisterUserOperator).
Use isInitialized() to check if the SDK is already configured before attempting initialization.

Core Features

Location Tracking

The SDK provides real-time location tracking capabilities through the Smart1Tracker singleton object, which uses Android Handlers for reliable background execution.

Setup Smart1Tracker

import com.servinformacion.smart1sdk.android.transmission.Smart1Tracker
import com.servinformacion.smart1sdk.android.transmission.Smart1TrackerDataProvider
import com.servinformacion.smart1sdk.android.transmission.model.Smart1TrackerConfig
import com.servinformacion.smart1sdk.android.transmission.types.Smart1TrackerLogLevel
import com.servinformacion.smart1sdk.android.transmission.types.Smart1TrackerProcessType
import com.servinformacion.smart1sdk.android.core.model.CoordinatesData
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import android.util.Log

class LocationTrackingService : Service() {
    
    private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
    
    private val dataProvider = object : Smart1TrackerDataProvider {
        override fun getLastLocation(): CoordinatesData? {
            // Return current device location from your location provider
            return CoordinatesData(
                latitude = 40.7128,
                longitude = -74.0060
            )
        }
        
        override fun getCompanyId(): Long? {
            return null
        }
    }
    
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        startTracking()
        return START_STICKY
    }
    
    private fun startTracking() {
        val config = Smart1TrackerConfig(
            reportTrackingTimeIntervalInMillis = 30000L, // 30 seconds
            inOutPortOnActiveOrderValidationTimeIntervalInMillis = 60000L, // 1 minute
            skipReportTrackingIfGPSIsDisabled = true
        )
        
        Smart1Tracker.start(
            config = config,
            provider = dataProvider,
            coroutineScope = scope,
            autoRestartOnError = true,
            onGettingInPort = { portId ->
                // Called when driver enters a port
                Log.d("Tracker", "Entered port: $portId")
                // Refresh app data to sync with server changes
                refreshLocalData()
            },
            onGettingOutPort = { portId ->
                // Called when driver exits a port
                Log.d("Tracker", "Exited port: $portId")
                // Refresh app data to sync with server changes
                refreshLocalData()
            },
            onLog = { level, processType, message ->
                // Optional: Monitor tracker events
                val tag = when (processType) {
                    Smart1TrackerProcessType.TRACKING -> "Tracking"
                    Smart1TrackerProcessType.PORT_VALIDATION -> "PortValidation"
                    Smart1TrackerProcessType.UNKNOWN -> "Tracker"
                    null -> "Tracker"
                }
                when (level) {
                    Smart1TrackerLogLevel.INFO -> Log.i(tag, message)
                    Smart1TrackerLogLevel.WARNING -> Log.w(tag, message)
                    Smart1TrackerLogLevel.ERROR -> Log.e(tag, message)
                }
            },
            onFatalError = {
                // Optional: Handle fatal errors (only if autoRestartOnError = false)
                Log.e("Tracker", "Fatal error occurred")
            }
        )
    }
    
    private fun refreshLocalData() {
        // Update local data when port events occur
        // Server may have updated schedules and orders automatically
    }
    
    fun notifyOrderStarted() {
        // Notify tracker when an order is set to "in progress"
        // This triggers immediate port validation instead of waiting for the next cycle
        Smart1Tracker.notifyNewOrderInProgress()
    }
    
    override fun onDestroy() {
        super.onDestroy()
        Smart1Tracker.stop()
    }
    
    override fun onBind(intent: Intent?): IBinder? = null
}

Smart1Tracker Configuration

Config Parameters:

reportTrackingTimeIntervalInMillis: Interval for sending location updates (minimum: 10,000ms)
inOutPortOnActiveOrderValidationTimeIntervalInMillis: Interval for checking port entry/exit (minimum: 10,000ms)
skipReportTrackingIfGPSIsDisabled: Skip tracking when GPS is disabled (default: false)

Start Parameters:

config: Tracker configuration (required)
provider: Location data provider (required)
coroutineScope: Coroutine scope for async operations (required)
autoRestartOnError: Auto-restart on errors (default: true)
onGettingInPort: Callback when entering a port (receives port ID)
onGettingOutPort: Callback when exiting a port (receives port ID)
onLog: Logging callback with level, process type, and message
onFatalError: Fatal error callback (only called if autoRestartOnError = false)

⚠️ Important Notes:

Singleton Pattern: Smart1Tracker is a singleton object - call methods directly without instantiation
Handler-Based: Uses Android Handlers for reliable background execution instead of coroutine loops
Auto-Recovery: Automatically recovers from temporary errors (GPS off, location null, etc.)
Data Synchronization: When port entry/exit events are detected, the server may automatically update the schedule of the active order. Refresh your app's local data when these callbacks are triggered.

Best Practice: Implement a single source of truth pattern using a local database. When port events trigger data updates, update this centralized store and let reactive observers (e.g., Flow collectors, LiveData) automatically propagate changes to all UI components.

Available Modules

The Smart1 SDK is organized into the following modules:

Core Modules

core - Base models, types, constants, and utilities used across all modules
initConfig - SDK session initialization and configuration

Authentication & User Management

auth - Session management and authentication
userOperator - User operator registration and profile management

Logistics Operations

order - Order management and tracking
route - Route planning and management
schedule - Schedule management
dock - Dock operations
port - Port management

Fleet Management

company - Company information and management
transmission - Real-time location tracking (Smart1Tracker)

Safety

panicAlarm - Emergency alert system

Documentation

Each module has its own Module.md file with detailed documentation:

./core/Module.md - Core functionality and data models
./initConfig/Module.md - SDK initialization
./auth/Module.md - Authentication and sessions
./userOperator/Module.md - User management
./transmission/Module.md - Location tracking
./order/Module.md - Order operations
./route/Module.md - Route management
./schedule/Module.md - Schedule operations
./dock/Module.md - Dock management
./port/Module.md - Port operations
./company/Module.md - Company management
./panicAlarm/Module.md - Emergency alerts

Quick Start Example

Here's a complete example showing SDK initialization and basic usage:

import android.app.Application
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.servinformacion.smart1sdk.android.init_config.Smart1SDK
import com.servinformacion.smart1sdk.android.init_config.InitSDKConfig
import com.servinformacion.smart1sdk.android.core.ResultS1SDK
import com.servinformacion.smart1sdk.android.user_operator.GetUserOperatorProfile

// 1. Initialize SDK in Application class
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Initialize Smart1 SDK
        Smart1SDK.initialize(this)
    }
}

// 2. Configure session and use SDK modules
class MainActivity : AppCompatActivity() {
    
    private val initSDKConfig = InitSDKConfig()
    private val getUserProfile = GetUserOperatorProfile()
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        initializeAndUseSDK()
    }
    
    private fun initializeAndUseSDK() {
        lifecycleScope.launch {
            // Step 1: Initialize SDK session
            val initResult = initSDKConfig.init(
                sdkApiKey = "your-sdk-api-key",
                email = "user@example.com"
            )
            
            when (initResult) {
                is ResultS1SDK.Success -> {
                    println("SDK initialized successfully")
                    loadUserProfile()
                }
                is ResultS1SDK.Error -> {
                    println("Failed to initialize: ${initResult.error}")
                }
            }
        }
    }
    
    private suspend fun loadUserProfile() {
        val profileResult = getUserProfile()
        
        when (profileResult) {
            is ResultS1SDK.Success -> {
                val profile = profileResult.data
                println("User: ${profile.name} ${profile.lastname}")
                println("Email: ${profile.email}")
            }
            is ResultS1SDK.Error -> {
                println("Failed to load profile: ${profileResult.error}")
            }
        }
    }
}

Required Plugins

The Smart1 SDK requires the following Gradle plugins to be applied to your project:

Gradle (Kotlin DSL)

Add these plugins to your build.gradle.kts:

plugins {
    id("org.jetbrains.kotlin.plugin.serialization") version "2.0.21"
    id("io.realm.kotlin") version "3.0.0"
}

Gradle (Groovy DSL)

Add these plugins to your build.gradle:

plugins {
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.21'
    id 'io.realm.kotlin' version '3.0.0'
}

Plugin Descriptions:

kotlin-serialization: Required for JSON serialization/deserialization
realm-kotlin: Required for local database operations

Required Dependencies

The Smart1 SDK requires the following dependencies to be added to your project:

Gradle (Kotlin DSL)

dependencies {
    // Ktor (Networking)
    implementation("io.ktor:ktor-client-core:2.3.8")
    implementation("io.ktor:ktor-client-android:2.3.8")
    implementation("io.ktor:ktor-client-okhttp:2.3.8")
    implementation("io.ktor:ktor-client-content-negotiation:2.3.8")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.8")
    implementation("io.ktor:ktor-client-logging:2.3.8")
    implementation("io.ktor:ktor-client-auth:2.3.8")
    
    // Koin (Dependency Injection)
    implementation("io.insert-koin:koin-core:3.5.3")
    implementation("io.insert-koin:koin-android:3.5.3")
        
    // Settings (Preferences)
    implementation("com.russhwolf:multiplatform-settings-no-arg:1.1.1")
    implementation("com.russhwolf:multiplatform-settings-coroutines:1.1.1")
    
    // Realm (Database)
    implementation("io.realm.kotlin:library-base:3.0.0")
    
    // Apache Avro (Serialization)
    implementation("org.apache.avro:avro:1.8.2")
    
    // AndroidX Security
    implementation("androidx.security:security-crypto:1.1.0")
}

Gradle (Groovy DSL)

dependencies {
    // Ktor (Networking)
    implementation 'io.ktor:ktor-client-core:2.3.8'
    implementation 'io.ktor:ktor-client-android:2.3.8'
    implementation 'io.ktor:ktor-client-okhttp:2.3.8'
    implementation 'io.ktor:ktor-client-content-negotiation:2.3.8'
    implementation 'io.ktor:ktor-serialization-kotlinx-json:2.3.8'
    implementation 'io.ktor:ktor-client-logging:2.3.8'
    implementation 'io.ktor:ktor-client-auth:2.3.8'
    
    // Koin (Dependency Injection)
    implementation 'io.insert-koin:koin-core:3.5.3'
    implementation 'io.insert-koin:koin-android:3.5.3'
        
    // Settings (Preferences)
    implementation 'com.russhwolf:multiplatform-settings-no-arg:1.1.1'
    implementation 'com.russhwolf:multiplatform-settings-coroutines:1.1.1'
    
    // Realm (Database)
    implementation 'io.realm.kotlin:library-base:3.0.0'
    
    // Apache Avro (Serialization)
    implementation 'org.apache.avro:avro:1.8.2'
    
    // AndroidX Security
    implementation 'androidx.security:security-crypto:1.1.0'
}

Maven

<dependencies>
    <!-- Ktor (Networking) -->
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-core</artifactId>
        <version>2.3.8</version>
    </dependency>
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-android</artifactId>
        <version>2.3.8</version>
    </dependency>
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp</artifactId>
        <version>2.3.8</version>
    </dependency>
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-content-negotiation</artifactId>
        <version>2.3.8</version>
    </dependency>
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-serialization-kotlinx-json</artifactId>
        <version>2.3.8</version>
    </dependency>
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-logging</artifactId>
        <version>2.3.8</version>
    </dependency>
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-auth</artifactId>
        <version>2.3.8</version>
    </dependency>
    
    <!-- Koin (Dependency Injection) -->
    <dependency>
        <groupId>io.insert-koin</groupId>
        <artifactId>koin-core</artifactId>
        <version>3.5.3</version>
    </dependency>
    <dependency>
        <groupId>io.insert-koin</groupId>
        <artifactId>koin-android</artifactId>
        <version>3.5.3</version>
    </dependency>
        
    <!-- Settings (Preferences) -->
    <dependency>
        <groupId>com.russhwolf</groupId>
        <artifactId>multiplatform-settings-no-arg</artifactId>
        <version>1.1.1</version>
    </dependency>
    <dependency>
        <groupId>com.russhwolf</groupId>
        <artifactId>multiplatform-settings-coroutines</artifactId>
        <version>1.1.1</version>
    </dependency>
    
    <!-- Realm (Database) -->
    <dependency>
        <groupId>io.realm.kotlin</groupId>
        <artifactId>library-base</artifactId>
        <version>3.0.0</version>
    </dependency>
    
    <!-- Apache Avro (Serialization) -->
    <dependency>
        <groupId>org.apache.avro</groupId>
        <artifactId>avro</artifactId>
        <version>1.8.2</version>
    </dependency>
    
    <!-- AndroidX Security -->
    <dependency>
        <groupId>androidx.security</groupId>
        <artifactId>security-crypto</artifactId>
        <version>1.1.0</version>
    </dependency>
</dependencies>

Required Permissions

Add the following permissions to your AndroidManifest.xml:

<!-- For network operations -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

All modules:

auth

This module provides authentication and session management functionality for the Smart1 SDK.

company

This module provides functionality to search and retrieve company information from the Smart1 SDK API.

core

This module provides core functionality, data models, types, and utilities used across all Smart1 SDK modules.

dock

This module provides functionality to search and retrieve dock information from the Smart1 SDK API.

initConfig

This module provides the initialization setup for the Smart1 SDK in Android applications.

order

This module provides functionality to search, retrieve, and manage orders from the Smart1 SDK API.

panicAlarm

This module provides functionality to send panic alarms to the Smart1 SDK API.

port

This module provides functionality to search and retrieve ports from the Smart1 SDK API.

route

This module provides functionality to search and retrieve routes from the Smart1 SDK API.

schedule

This module provides functionality to search and retrieve schedules from the Smart1 SDK API.

transmission

This module provides functionality for real-time location tracking and port entry/exit detection for the Smart1 SDK.

userOperator

This module provides user operator management functionality for the Smart1 SDK.