Android Integration

This guide provides instructions for integrating the FleetShare SDK into an Android application. On Android the SDK ships as an .aar and exposes the same FleetSdk API as the Java guide — the differences are how you add the dependency and that baseDir must be the app’s files directory.

Requirements

1. Add the .aar. Copy sdkfleet-release.aar into your module (e.g. app/libs/) and reference it in app/build.gradle:

dependencies {
    implementation(files("libs/sdkfleet-release.aar"))
}

2. Add permissions in AndroidManifest.xml:

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

• minSdk 19 (Android 4.4+).
• org.json is part of the Android framework — there is nothing extra to add.

Parameters

• apiKey: Your API key from the FleetShare SDK program.
• deviceName: A name for the device running the SDK.
• showLogs: (Optional) If set to true, the SDK prints logs.
• baseDir: Where the SDK stores its files (the downloaded native library and internal state). On Android, pass your app’s private files directory: context.getFilesDir().getAbsolutePath().

Methods

User Consent (required)

You must obtain the user’s consent and record it with EarnFM before starting the SDK. The server rejects any device that does not have a granted consent on record.

The flow is simple:

initialize()  →  show a consent prompt  →  storeConsent(...)  →  startSdk()

storeConsent(consentText, consentTextHash, action, metadata) records the user’s decision (action is "grant" or "revoke") and returns true on success. Only call startSdk() after a successful grant, and send a revoke if the user later opts out in your settings.

For the full parameter reference, the recommended default consent text, and the underlying HTTP endpoint, see the Consent API page.

Example Implementation

package com.example.myapp

import android.content.Context
import com.fleet.FleetSdk

object Fleet {
    private const val API_KEY = "YOUR_API_KEY"
    private const val DEVICE_NAME = "My Android Device"

    // Call this from a background thread. `userAccepted` comes from your consent dialog.
    fun start(context: Context, userAccepted: Boolean) {
        val sdk = FleetSdk(API_KEY, DEVICE_NAME, false, context.filesDir.absolutePath)

        if (!sdk.initialize()) return

        // Record the user's decision. Supply the consent text OR its hash (null for the other);
        // metadata is any JSON that uniquely identifies the user.
        val consentText = "Run Earn.FM in background?"
        val metadata = """{"user":"your-user-identifier"}"""
        val recorded = sdk.storeConsent(consentText, null, if (userAccepted) "grant" else "revoke", metadata)

        // Only start sharing if the user granted consent and it was recorded.
        if (userAccepted && recorded) {
            sdk.startSdk()
        }
    }
}

Call it after the user makes their choice in your consent UI — on a background thread:

// e.g. in your Activity, once the user has tapped Accept/Decline:
Thread {
    Fleet.start(applicationContext, userAccepted = true)
}.start()

Best Practices

1. Threading: Run initialize(), storeConsent(), and startSdk() off the main/UI thread.
2. User Consent: Always record the user’s consent decision with storeConsent(...) before starting, and send a revoke if they later opt out in your app’s settings.
3. Error Handling: Handle network and initialization failures gracefully.
4. Updating the SDK: Stay updated with new SDK versions, as older versions may become deprecated.

Troubleshooting

If you encounter any issues while integrating or using the FleetShare SDK, consider the following:

1. Ensure the INTERNET permission is declared and the device has connectivity — the app must reach cdn.earn.fm, api.earn.fm, and socket-prod.earn.fm.
2. Make sure you call the SDK from a background thread, not the main thread.
3. Confirm the .aar is correctly referenced and minSdk is 19 or higher.
4. Verify that your API key is correct and active.
5. If the native library fails to load on very recent Android versions with strict security policies, contact the FleetShare team — the SDK may need to load it from an alternate location.
6. Do not modify the SDK’s internal code. Doing so may cause unexpected behavior or errors.

For further assistance, please contact the FleetShare support team with the proper logs (set showLogs to true to get logs).