🚗 In-Vehicle Auto-Start (Activity Recognition)

The :speed-autostart module provides zero-touch background trip detection using Google Play Services Activity Recognition API. It eliminates user friction by automatically starting speed tracking when the driver enters a vehicle and halting it upon exit to preserve battery.

---

🎯 Why Activity Recognition Over Background GPS?

Continuous background GPS polling drains the device battery rapidly and triggers severe Google Play Store rejection risks under background location policies.

By using Activity Recognition (DetectedActivity.IN_VEHICLE):

• Hardware Co-Processor Power: Runs on low-power sensor hubs without waking the main CPU.
• Zero Location Polling When Idle: The GPS radio remains powered off until the vehicle begins moving.
• Automatic Teardown: When the driver parks and walks away (ACTIVITY_TRANSITION_EXIT), the SDK shuts down the foreground service automatically.

---

📦 Gradle Dependency

Add :speed-autostart to your build.gradle.kts:

dependencies {
    implementation(platform("com.vegsahayyak:speed-bom:2.2.0"))
    implementation("com.vegsahayyak:speed-core")
    implementation("com.vegsahayyak:speed-autostart")
}

---

💻 Registering Auto-Start (AutoStartManager)

Enable auto-start with runtime permission handling:

import com.vegsahayyak.speedautostart.AutoStartManager

AutoStartManager.enable(
    context = context,
    onPermissionRequired = {
        // Android 10+ (API 29+) requires Manifest.permission.ACTIVITY_RECOGNITION
        ActivityCompat.requestPermissions(
            activity,
            arrayOf(android.Manifest.permission.ACTIVITY_RECOGNITION),
            REQUEST_CODE_ACTIVITY_RECOGNITION
        )
    },
    onSuccess = {
        // Successfully registered with Google Play Services!
        // SpeedAssistant will now auto-start when vehicle motion is detected.
    },
    onError = { exception ->
        Log.e("Telematics", "Activity Recognition registration failed", exception)
    }
)

---

📡 How the Receiver Operates (AutoStartReceiver)

The SDK bundles AutoStartReceiver in its internal manifest. When Google Play Services fires an activity transition event:

// Automatically handled by :speed-autostart
when (event.activityType) {
    DetectedActivity.IN_VEHICLE -> {
        when (event.transitionType) {
            ActivityTransition.ACTIVITY_TRANSITION_ENTER -> {
                SpeedAssistant.with(context, "YOUR_JWT_LICENSE").start()
            }
            ActivityTransition.ACTIVITY_TRANSITION_EXIT -> {
                SpeedAssistant.with(context, "YOUR_JWT_LICENSE").stop()
            }
        }
    }
}

---

🛡️ Android Manifest Requirements

Ensure the activity recognition permission is declared in your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required for Android 10+ (API 29+) -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
</manifest>

TIP

Passenger Mode: If a user is riding as a passenger (e.g. on a bus or train), your app can provide a "Passenger Mode" pause toggle that calls SpeedAssistant.with(context, "YOUR_JWT_LICENSE").stop(), overriding auto-start until the next journey.