Integration Guides
NodeJS Integration

NodeJS Integration

This guide provides instructions for integrating the FleetShare SDK into a Node.js application (desktop or server). The SDK runs asynchronously so it works concurrently with your main application logic.

Requirements

The FleetShare team provides the SDK as an npm tarball (earnfm-nodejs-sdk-x.y.z.tgz). Install that file as a local dependency — you do not copy source files into your project.

  • Node.js 18 or newer
  • npm
  • A writable directory for the downloaded native library and device state
  • Outbound access to *.earn.fm and the backup domain *.earnfm.fo

On Linux the native library is glibc-based — Debian/Ubuntu/RHEL/Amazon Linux work. Alpine (musl) does not.

Supported native targets: macOS (amd64/arm64), Windows (amd64/arm64), Linux (amd64/arm64/arm).

Installation

Install the .tgz you received from the FleetShare team:

npm install ./earnfm-nodejs-sdk-3.0.0.tgz

npm pulls in koffi automatically. On initialize() the SDK downloads the native library for the current OS from EarnFM’s CDN — you do not ship those binaries yourself.

const FleetSdk = require('earnfm-nodejs-sdk');

Do not unpack or edit the tarball contents.

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 its wrapper logs to the console.
  • baseDir: (Optional) Directory where the SDK stores its files (the downloaded native library and internal state). If omitted or null, it uses the current working directory. Set an absolute path (e.g. /opt/fleet) when you need a fixed, writable location.
  • storeLogs: (Optional, default true) Writes the native library’s logs to a file under baseDir (see Logs). This is independent of showLogs. Can only be set through the options object.

Constructor: new FleetSdk(apiKey, deviceName, showLogs = false, baseDir = null).

You can also pass an options object: { apiKey, deviceName, showLogs, baseDir, storeLogs }. Note that storeLogs is only available through the options object.

Methods

Method Returns Description
initialize() Promise<boolean> Prepares the SDK — downloads/loads the native library and starts the local service. Call this first.
getDeviceId() string Stable device id used for consent and earning. Available after initialize().
storeConsent(consentText, consentTextHash, action, metadata) Promise<boolean> Records the user’s consent decision. Call after initialize() and before startSdk().
startSdk() Promise<boolean> Starts bandwidth sharing.
stopSdk() Promise<boolean> Stops bandwidth sharing.
getStatus() Promise<object|null> { current_status, error } from the local service. 2 = connected, 1 = connecting, 0 = not connected, -1 = error.
destroyServer() Promise<boolean> Stops sharing, stops the native server, and resets state.

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.

Show the user the consent prompt, then pass that exact text (or its hash) into storeConsent. For the recommended default wording and the full parameter reference, see the Consent API page.

Example Implementation 

const FleetSdk = require('earnfm-nodejs-sdk');

const API_KEY = 'YOUR_API_KEY';
const DEVICE_NAME = 'ANY_RANDOM_NAME';
const showLogs = false;
const baseDir = null; // or an absolute writable path

async function main() {
    const sdk = new FleetSdk(API_KEY, DEVICE_NAME, showLogs, baseDir);

    if (!await sdk.initialize()) {
        console.error('Failed to initialize SDK.');
        return;
    }

    // 1) Show your consent prompt and capture the user's choice.
    //    Use the recommended copy from the Consent API docs.
    const consentText = 'Support YourApp by sharing your unused internet bandwidth. ...';
    const userAccepted = await showConsentPromptToUser(consentText);

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

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

    if (!await sdk.startSdk()) {
        console.error('Failed to start SDK.');
        return;
    }

    console.log('SDK started.');
}

// Replace this with your real consent UI / decision.
async function showConsentPromptToUser(consentText) {
    console.log(consentText);
    return true;
}

main().catch((err) => {
    console.error(err);
    process.exit(1);
});

Logs

The SDK produces two separate log streams:

  • Wrapper logs — the FleetSdk: lines from the Node layer. Printed to the console only when showLogs is true.

  • Native logs — the detailed connection and relay activity from the native library. With storeLogs on (the default) they are written to:

    <baseDir>/fleetshare_data/fleetshare.log

    With the default baseDir that resolves to ./fleetshare_data/fleetshare.log. This file is written even when showLogs is false, and it is overwritten at the start of each run — copy it before restarting if you need to keep a session.

When reporting a problem, send this fleetshare.log file — it contains the full native-side detail the support team relies on. To turn file logging off, construct with { storeLogs: false }; the native logs then go to stderr instead.

Requires native library 2.3.4 or newer. Older libraries skip the file and send native logs to stderr.

Best Practices

  1. Error Handling: Check the boolean returns from initialize(), storeConsent(), and startSdk().
  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: Install the new .tgz from the FleetShare team when a new version is issued. The native library on the CDN updates itself; the Node wrapper does not.
  4. API keys: Keep the API key in an environment variable rather than hardcoding it.

Troubleshooting

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

  1. Ensure you’re using the latest .tgz from the FleetShare team.
  2. Confirm npm install ./earnfm-nodejs-sdk-x.y.z.tgz completed and koffi is present in node_modules.
  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 *.earn.fm and *.earnfm.fo.
  5. Confirm your Node.js version is 18 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 installed package. Doing so may cause unexpected behavior or errors.

For further assistance, contact the FleetShare support team and include the native log file — <baseDir>/fleetshare_data/fleetshare.log (see Logs). It captures the full native-side detail support needs; console output alone (showLogs) is usually not enough.

Kotlin IntegrationPython Integration