Mobile SDK Android

How to start

Adding the Geotab Mobile SDK as a dependency

Geotab Mobile SDK can be added as gradle dependency, which is hosted in a GitHub repository. Use a valid GitHub user and token to access the library. Update build.gradle inside the app module with the Geotab Mobile SDK's Github repository path and credentials.

repositories {
    /**
     * Create local.properties in root project folder file.
     * Add properties gpr.usr=GITHUB_USERID and gpr.key=PERSONAL_ACCESS_TOKEN.
     * Replace GITHUB_USERID with Github User ID and PERSONAL_ACCESS_TOKEN with a personal access token for this user.
     */
    File localPropertiesFile = rootProject.file("local.properties")
    Properties localProperties = new Properties()
    if (localPropertiesFile.exists()) {
        localProperties.load(localPropertiesFile.newDataInputStream())
    }

    maven {
        name = "GitHubPackages"
        url = uri {"https://maven.pkg.github.com/geotab/mobile-sdk-android"}
        credentials {
            username = localProperties["gpr.usr"]
            password = localProperties["gpr.key"]
        }
    }
}

check this to create a personal access token, from the user account. Select the read:packages option when selecting your token's scope.

Add the Geotab Mobile SDK library under the dependencies, to the application's build gradle.

dependencies {
    implementation 'com.geotab.mobile.sdk:mobile-sdk-android:$sdk_version'
}

Sync project with Gradle files to ensure the dependencies are resolved.

Initialization

The DriveFragment is the starting point of integrating mobile SDK. It's the container of the Geotab Drive Web app equipped with native APIs for accessing Geotab Drive web app's data

val driveView = DriveFragment.newInstance()  

Present the DriveFragment

supportFragmentManager
    .beginTransaction()
    .add(R.id.main_layout, driveView)
    .commit()

Execute API call

Most API calls require a user to be logged in to get a meaningful result. You can listen for the setPageNavigationCallback to know when the user has successfully logged in.

driveView.setPageNavigationCallback { path ->
    Log.d(tag, "PageNavigationCallback: $path")
    if (path.contains("main")) {
        //User is logged in
    }
}

Now you can make API calls like getUserViolations to get the logged in user's HOS violations.

driveView.getUserViolations { result ->
    when (result) {
        is Success -> {
            for (violation in result.value) {
                Log.d(tag, "Successful get violation $violation")
            }
        }
        is Failure -> {
            Log.d(
                tag, "Get violations failed with ${result.reason.getErrorCode()}," +
                    result.reason.getErrorMessage()
            )
        }
    }
}

For a complete list of APIs see geotabdrivesdk

Set a Callback listener

driveView.setDriverActionNecessaryCallback { (isDriverActionNecessary, driverActionType) ->
    Log.d(tag, "DriverActionNecessaryCallback: $isDriverActionNecessary, $driverActionType ")
}

For a complete list of callbacks see geotabdrivesdk

Custom Login

The Mobile SDK allows integrators to use their own authentication and user management. All the SDK needs to log into Geotab Drive is a user's credentials.

driveView.setSession(credentials, isCoDriver)

Where credentials is of type CredentialResult and isCoDriver is a Boolean

data class CredentialResult(
    val credentials: GeotabCredentials,
    val path: String
) : Serializable

data class GeotabCredentials(
    val userName: String,
    val database: String,
    val sessionId: String
) : Serializable

Overwrite Default Background Service Notification Icon

To use a custom icon for the foreground service notification, create a metadata object in your AndroidManifest.xml

<meta-data
    android:name="default_notification_icon"
    android:resource="@drawable/your_icon" />

Overwrite Default Background color and icon

To override default background color in network error page, create color resource with name="whitelabel_background_color" in color.xml

<color name="whitelabel_background_color">#FFFFFF</color>

To override default text color in network error page, create color resource with name="whitelabel_text_color" in color.xml

<color name="whitelabel_text_color">#FBCE07</color>

To override default icon in network error page, add a drawable resource with name="whitelabel_banner_icon"

Permissions

Geotab Mobile SDK offers native notification alerts to drivers concerning both Hours of Service (HOS) violations and availability status, even when the app is in the background. Following permissions are required for Android SDK 34 and above, to use the foreground service functionality.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" android:minSdkVersion="34" />

To use the background location functionality, just add the permission in your AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

License

GeotabDriveSDK is available under the MIT license. See the LICENSE file for more info.