Java Integration

This guide provides instructions for integrating the FleetShare SDK into a Java application (desktop or server). The SDK runs on its own threads so it works concurrently with your main application logic. Java is a widely-used, object-oriented language known for its “write once, run anywhere” capability.

Requirements

The FleetShare team provides the SDK as a single .jar, available in two forms:

• Self-contained (FleetSdk-all.jar) — org.json is bundled in, so there is nothing else to add. Recommended.
• Thin (FleetSdk.jar) — you add the org.json dependency yourself.

If you use the thin jar, add org.json. For Maven (pom.xml):

<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20231013</version>
</dependency>

For Gradle (build.gradle):

dependencies {
    implementation 'org.json:json:20231013'
}

The SDK requires Java 11 or newer.

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 to the console.
• baseDir: The directory where the SDK stores its files (the downloaded native library and internal state). If set to null, it uses the current working directory. Set an absolute path (e.g. /opt/fleet) when you need a fixed, writable location.

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.

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

Example Implementation

package org.example;

import com.fleet.FleetSdk;

public class Main {
    private static final Object lock = new Object();
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String DEVICE_NAME = "ANY_RANDOM_NAME";
    private static final boolean showLogs = false;

    // baseDir is where all files are stored. Pass an absolute path if the SDK needs a
    // specific writable location; null uses the current working directory.
    private static final String baseDir = null;

    public static void main(String[] args) throws Exception {
        FleetSdk sdk = new FleetSdk(API_KEY, DEVICE_NAME, showLogs, baseDir);

        if (!sdk.initialize()) {
            System.err.println("Failed to initialize SDK.");
            return;
        }

        // 1) Show your consent prompt and capture the user's choice.
        String consentText = "Run Earn.FM in background?";
        boolean userAccepted = showConsentPromptToUser(); // <-- your UI / logic

        // 2) Record the decision. Supply the consent text OR its hash (null for the other);
        //    metadata is any JSON that uniquely identifies the user.
        String metadata = "{\"user\":\"your-user-identifier\"}";
        boolean recorded = sdk.storeConsent(consentText, null, userAccepted ? "grant" : "revoke", metadata);

        // 3) Only start sharing if the user granted consent and it was recorded.
        if (!userAccepted || !recorded) {
            System.out.println("Consent not granted. Not starting the SDK.");
            return;
        }

        if (!sdk.startSdk()) {
            System.err.println("Failed to start SDK.");
            return;
        }

        System.out.println("SDK started. Holding main thread...");
        synchronized (lock) {
            lock.wait();
        }
    }

    // Replace this with your real consent UI / decision.
    private static boolean showConsentPromptToUser() {
        return true;
    }
}

Best Practices

1. Error Handling: Implement robust error handling to manage potential issues that may arise during SDK operation.
2. User Consent: Always record the user’s consent decision with storeConsent(...) before starting, and send a revoke if they later opt out.
3. Updating the SDK: Stay updated with new SDK versions and handle updates gracefully, as older versions may become deprecated.
4. Resource Management: Be mindful of system resources. The SDK is designed to run efficiently, but you should monitor its impact on your application’s performance.

Ensure you follow these best practices to maintain a secure and user-friendly application.

Troubleshooting

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

1. Ensure you’re using the latest version of the SDK.
2. Check that all required dependencies are correctly added (or use the self-contained jar).
3. Verify that your API key is correct and active.
4. If you’re experiencing connection issues, check your network connectivity — the host must reach cdn.earn.fm, api.earn.fm, and socket-prod.earn.fm.
5. Confirm your Java version is 11 or newer.
6. On Linux, the native library is glibc-based — it runs on Debian/Ubuntu/RHEL/Amazon Linux, but not on Alpine (musl).
7. 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).