Android integration options

GetPassive is currently a Node.js SDK, not a native Android AAR. This guide explains the honest supported paths for Android apps today and the caveats to test before release.

Choose an approach

Approach A: Capacitor (recommended)

Use Capacitor when your Android app is already a JavaScript app wrapped in a native shell. The current SDK is Node.js-only, so the Android shell must provide a Node-compatible runtime or a native bridge that launches a small Node helper. A plain browser WebView alone cannot run the current package.

1. Install the web app and SDK

npm install @capacitor/core @capacitor/android
npm install @getpassive/sdk

2. Create a consent-gated helper module

// getpassive-helper.mjs - executed by your Node-capable Capacitor bridge.
import { GetPassiveClient } from '@getpassive/sdk';

let client;

export async function startGetPassive({ devApiKey, deviceUuid }) {
  if (client) return;
  client = new GetPassiveClient({
    devApiKey,
    deviceUuid,
    onStatus: (status) => console.log('[getpassive]', status),
    onError: (error) => console.error('[getpassive]', error),
  });
  await client.start();
}

export async function stopGetPassive() {
  if (!client) return;
  await client.stop();
  client = undefined;
}

3. Wire consent and settings toggle

async function onConsentAccepted() {
  await NativeNodeBridge.startGetPassive({
    devApiKey: process.env.GETPASSIVE_DEV_API_KEY,
    deviceUuid: await loadStableDeviceUuid(),
  });
}

async function onUserOptedOut() {
  await NativeNodeBridge.stopGetPassive();
}

Caveats: confirm Android background execution rules, battery-optimization prompts, and process lifecycle for your chosen Node bridge. Start only after consent and stop immediately on opt-out.

Approach B: React Native bridge

React Native cannot import the current SDK directly in the JavaScriptCore/Hermes runtime because the SDK depends on Node.js APIs and the ws package. Use a bridge such as nodejs-mobile-react-native to run a separate Node.js worker, then communicate with it from React Native.

npm install nodejs-mobile-react-native
npm install @getpassive/sdk

// nodejs-assets/node-main.js
import rnBridge from 'rn-bridge';
import { GetPassiveClient } from '@getpassive/sdk';

let client;

rnBridge.channel.on('message', async (message) => {
  if (message.type === 'start-getpassive' && !client) {
    client = new GetPassiveClient({
      devApiKey: message.devApiKey,
      deviceUuid: message.deviceUuid,
      onStatus: (status) => rnBridge.channel.send({ type: 'status', status }),
      onError: (error) => rnBridge.channel.send({ type: 'error', message: String(error) }),
    });
    await client.start();
  }

  if (message.type === 'stop-getpassive' && client) {
    await client.stop();
    client = undefined;
  }
});

// React Native side - send only after the user has accepted consent.
nodejs.channel.send({
  type: 'start-getpassive',
  devApiKey: Config.GETPASSIVE_DEV_API_KEY,
  deviceUuid: stableDeviceUuid,
});

Choose this when: your app is already React Native and your team is comfortable owning a background Node bridge. Test app-store policy, startup time, and low-memory behavior on real devices before release.

Approach C: WebView (limited)

A WebView can host your consent UI and dashboard-facing app screens, but it cannot run the current @getpassive/sdk package by itself. Browser/WebView SDK support is planned for a future version.

// Placeholder only. The current Node.js SDK cannot be started from a plain WebView.
if (window.GetPassiveBrowserSDK) {
  await window.GetPassiveBrowserSDK.start({ apiKey, consent: true });
}

Choose this when: you are designing the UI now and can wait for a browser SDK before enabling bandwidth sharing. Do not claim Android support in production until the SDK runtime is actually present.

Consent and review

• Show the disclosure before starting any helper process or bridge.
• Provide a settings toggle that stops the SDK and persists the opt-out state.
• Submit consent changes for re-review under the compliance policy.
• See the consent guide for suggested wording.

Native Android roadmap

For native Java/Kotlin SDK support, contact partnerships at [email protected] — we're collecting demand signal.

Last updated June 29, 2026