Getting Started

Welcome to the Veg Sahayyak SDK integration guide. This document guides you through configuring your Android build, authenticating with GitHub Packages, declaring dependencies, and executing your first background telematics tracking session.

---

📋 Minimum Requirements

Before integrating the SDK, ensure your project environment meets the following specifications:

Requirement	Minimum Supported	Recommended Target
Android Minimum SDK (minSdk)	API 23 (Android 6.0)	API 26 (Android 8.0+)
Android Target SDK (targetSdk)	API 34	API 35 / API 37
Kotlin Version	1.9.20+	2.0.0+ / 2.2.0
JDK Version	Java 17	Java 21
Jetpack Compose	2024.04.00 (BOM)	Latest Stable Compose BOM

---

🔑 1. Authentication with GitHub Packages

Veg Sahayyak SDK artifacts are distributed privately via GitHub Packages Maven Registry. To resolve dependencies, you must supply a GitHub Personal Access Token (PAT) with read:packages scope.

Step A: Configure Authentication Credentials

We strongly recommend storing your credentials securely in your local.properties file or environment variables to avoid checking secrets into version control:

# In your project's local.properties (git-ignored)
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step B: Add Repository to Gradle

Add the registry to your settings.gradle.kts (or root build.gradle.kts):

settings.gradle.kts (Kotlin DSL)

import java.util.Properties

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        
        // Veg Sahayyak SDK Private Registry
        maven {
            name = "VegSahayyakSDK"
            url = uri("https://maven.pkg.github.com/VegSahayyak/veg-sahayyak-sdk")
            credentials {
                val localProps = Properties().apply {
                    val file = rootProject.file("local.properties")
                    if (file.exists()) file.inputStream().use { load(it) }
                }
                username = System.getenv("GITHUB_ACTOR") 
                    ?: localProps.getProperty("gpr.user") 
                    ?: (project.findProperty("gpr.user") as String?)
                password = System.getenv("GITHUB_TOKEN") 
                    ?: localProps.getProperty("gpr.key") 
                    ?: (project.findProperty("gpr.key") as String?)
            }
        }
    }
}

settings.gradle (Groovy DSL)

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        
        maven {
            name = "VegSahayyakSDK"
            url = uri("https://maven.pkg.github.com/VegSahayyak/veg-sahayyak-sdk")
            credentials {
                username = System.getenv("GITHUB_ACTOR") ?: project.findProperty("gpr.user")
                password = System.getenv("GITHUB_TOKEN") ?: project.findProperty("gpr.key")
            }
        }
    }
}

---

📦 2. Dependency Declaration

The SDK is divided into modular artifacts. Using the Bill of Materials (BOM) is the recommended approach to guarantee version alignment.

app/build.gradle.kts (Recommended with BOM)

dependencies {
    // 1. Import the Veg Sahayyak BOM
    implementation(platform("com.vegsahayyak:speed-bom:2.2.0"))

    // 2. Core headless tracking, FusedLocation & TelematicsEngine
    implementation("com.vegsahayyak:speed-core")

    // 3. Optional Compose UI components (SpeedGauge, HudDisplay, Themes)
    implementation("com.vegsahayyak:speed-ui")

    // 4. Optional PiP floating speedometer overlay widget
    implementation("com.vegsahayyak:speed-overlay")

    // 5. Optional automatic zero-touch trip start via Activity Recognition
    implementation("com.vegsahayyak:speed-autostart")
}

app/build.gradle.kts (Pure Headless / XML View-Only)

dependencies {
    // For non-Compose projects: import only the core telematics engine
    implementation(platform("com.vegsahayyak:speed-bom:2.2.0"))
    implementation("com.vegsahayyak:speed-core")
    // Zero Compose dependencies added to your project!
}

TIP

XML Layouts & ViewBinding Support: If your application is built with traditional XML layouts rather than Jetpack Compose, you have two options:

1. Headless XML Binding: Import only :speed-core and bind SpeedAssistant.observeFlow() to standard TextView and ProgressBar widgets.
2. ComposeView Interop: Import :speed-ui and embed <androidx.compose.ui.platform.ComposeView> directly inside your XML layout file. See the XML Integration Guide.

---

🛡️ 3. Android Manifest Permissions

The SDK requires standard Android Location and Foreground Service permissions. Add the following to your app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Fine and Coarse GPS Permissions -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

    <!-- Android 10+ Background Location (for persistent fleet tracking) -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

    <!-- Android 14+ Foreground Service Location Type -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

    <!-- Android 13+ Notification Post Permission -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <!-- Audio & Haptics for Alarm Alerts -->
    <uses-permission android:name="android.permission.VIBRATE" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />

    <!-- Optional: For PIP Widget / Floating Overlay -->
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

    <!-- Optional: For Activity Recognition (Auto-Start) (Android 10+) -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

    <!-- Optional: For Voice Commands -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />

</manifest>

NOTE

The SDK's speed-core module includes the SpeedometerService pre-configured in its internal Android Manifest with android:foregroundServiceType="location". You do not need to redeclare the service in your app manifest.

---

🔒 4. ProGuard & R8 Optimization Rules

If your application enables code obfuscation (minifyEnabled = true), the SDK includes consumer Proguard rules automatically. If needed, you can explicitly verify these rules:

# Veg Sahayyak SDK Model & Data Retention
-keep class com.vegsahayyak.speedcore.data.location.SpeedData** { *; }
-keep class com.vegsahayyak.speedcore.domain.TelematicsResult { *; }
-keep class com.vegsahayyak.speedcore.units.SpeedUnit { *; }
-keep class com.vegsahayyak.speedcore.api.DrivingProfile** { *; }
-keep class com.vegsahayyak.speedui.api.VoiceAction** { *; }
-keep interface com.vegsahayyak.speedcore.api.** { *; }

---

🔑 5. Commercial JWT Licensing

The Veg Sahayyak SDK requires an offline-first JSON Web Token (JWT) to initialize. This token encodes your organization's permitted module access and expiry dates securely using the Native C++ libveg_vault.so library.

You will receive this JWT from your Veg Sahayyak account manager.

---

⚡ 6. Verify Installation

In your MainActivity.kt, verify that the SDK compiles and initializes with your JWT:

import com.vegsahayyak.speedcore.api.SpeedAssistant
import com.vegsahayyak.speedcore.api.DrivingProfile

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val enterpriseJwt = "eyJhbGciOi..." // Your actual JWT here
        
        // Initialize the SDK with your License and apply a driving profile
        val assistant = SpeedAssistant.with(this, enterpriseJwt)
        assistant.setDrivingProfile(DrivingProfile.CarHighway)

        
        android.util.Log.d("SpeedAssistant", "SDK initialized with Highway Profile!")
    }
}

💡 Ready-to-Run Sample Applications

Prefer learning by example? Check out our public sample repository at github.com/VegSahayyak/veg-sahayyak-samples featuring 6 complete reference architectures (Fleet Management, Usage-Based Insurance, Background Auto-Start, PiP Floating Overlay, and Custom Gauge UI).

👉 Next Up: Learn about the SDK Architecture Overview and how the signal processing algorithms work under the hood.