@orange/speedtest-react-native

React Native bridge for running real Speedchecker speed tests in native code.

The JavaScript API is intentionally thin:

import {
  addProgressListener,
  configure,
  start,
  stop,
  SpeedTestView,
} from '@orange/speedtest-react-native';

React Native never performs the measurement. The app calls this package, the package calls the native iOS or Android module, and the native module calls the Speedchecker SDK.

Install

npm install @orange/speedtest-react-native
cd ios
bundle exec pod install

For local validation from this repository:

cd orange-speedtest-react-native/example
npm install
cd ios && bundle exec pod install && cd ..
npm run ios
npm run android

Speedchecker Configuration

License keys are provided at runtime, not hardcoded:

await configure({
  licenseKey: '<from secure app config>',
  requestLocationPermission: true,
});

const result = await start({
  downloadTimeMs: 10000,
  uploadTimeMs: 10000,
  sendResultsToSpeedChecker: true,
});

If licenseKey is empty, the SDK runs in Speedchecker free mode. Free mode requires location permission according to Speedchecker’s SDK requirements.

API

configure(options: SpeedTestConfig): Promise<void>
start(options?: SpeedTestOptions): Promise<SpeedTestResult>
stop(): Promise<void>
addProgressListener(listener): { remove(): void }
removeProgressListener(listener): void
openNativeScreen(options?: SpeedTestOptions): Promise<void>

Supported phases:

'idle' | 'initializing' | 'latency' | 'download' | 'upload' | 'completed' | 'error' | 'cancelled'

Progress events include:

{
  phase: 'download',
  progress: 0.42,
  speedMbps: 135.5,
  pingMs: 18,
  jitterMs: 3,
  timestamp: '2026-05-20T10:20:30.000Z'
}

Final results include:

{
  downloadMbps: 135.5,
  uploadMbps: 32.1,
  pingMs: 18,
  jitterMs: 3,
  latencyMs: 18,
  packetLossPercent: 0,
  clientInfo: { ipAddress: '...', ispName: '...' },
  serverInfo: { domain: '...', city: '...' },
  timestamp: '2026-05-20T10:20:30.000Z'
}

SpeedTestView

SpeedTestView is a ready-to-use validation component. It calls configure(), starts and stops native tests, listens to progress events, and displays phase, progress, speed, final result, and errors.

<SpeedTestView
  config={{
    licenseKey,
    requestLocationPermission: true,
  }}
  options={{
    downloadTimeMs: 10000,
    uploadTimeMs: 10000,
    sendResultsToSpeedChecker: true,
  }}
/>

iOS Setup

The podspec depends on:

pod 'SpeedcheckerSDK', '~> 2.2.13'

The host app must provide:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location is used to select a nearby speed test server.</string>

Background location is not requested by this package. If a paid Speedchecker background measurement product is added later, configure those Info.plist keys in the host app explicitly.

If CocoaPods needs framework linkage for the Speedchecker SDK, run pods with:

USE_FRAMEWORKS=static bundle exec pod install

Android Setup

The library manifest includes:

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

It does not include ACCESS_BACKGROUND_LOCATION.

The Speedchecker Android SDK declares cleartext traffic support for its measurement endpoints. If the host app already sets android:usesCleartextTraffic, add tools:replace="android:usesCleartextTraffic" on the <application> element and choose the value required by your Speedchecker/server setup.

Speedchecker’s Maven repository requires credentials. Put them in the host app’s gradle.properties, CI secrets, or environment:

SPEEDCHECKER_MAVEN_USERNAME=...
SPEEDCHECKER_MAVEN_PASSWORD=...
SPEEDCHECKER_ANDROID_SDK_VERSION=4.2.299

Environment variable names are the same. Credentials are never stored in this package.

The host app must also expose Speedchecker’s Maven repository from the root Android Gradle project:

def speedcheckerProperty = { name ->
  providers.gradleProperty(name)
    .orElse(providers.environmentVariable(name))
    .orNull
}

allprojects {
  repositories {
    maven {
      url = uri("https://maven.speedcheckerapi.com/artifactory/libs-release")
      def speedcheckerUsername = speedcheckerProperty("SPEEDCHECKER_MAVEN_USERNAME")
      def speedcheckerPassword = speedcheckerProperty("SPEEDCHECKER_MAVEN_PASSWORD")
      if (speedcheckerUsername != null && speedcheckerPassword != null) {
        credentials {
          username = speedcheckerUsername
          password = speedcheckerPassword
        }
      }
    }
  }
}

The package adds consumer R8 rules for Speedchecker classes:

-keep class com.speedchecker.** { *; }
-dontwarn com.speedchecker.**

Bridge Flow

React Native app
  -> @orange/speedtest-react-native
  -> OrangeSpeedTest native module
  -> Speedchecker iOS SDK / Speedchecker Android SDK
  -> progress, result, error, cancelled events
  -> React Native UI

Native event names:

OrangeSpeedTestProgress
OrangeSpeedTestResult
OrangeSpeedTestError
OrangeSpeedTestCancelled

start() resolves with SpeedTestResult when the native SDK finishes and rejects when the native SDK reports an error or cancellation.

Native Screens

openNativeScreen() presents a small native validation screen on iOS and Android. It still uses the Speedchecker native SDK for measurements. The screen is intentionally simple and meant for package validation, while app-specific UI should use the TypeScript API or SpeedTestView.

Known Limitations

• The package covers Speedchecker speed-test measurements. Background tests, launch tests, YouTube, WiFi router, and VoIP tests are not exposed.
• iOS custom server selection is not exposed in this first bridge surface.
• Android custom server support is mapped through Speedchecker’s Server object; validate field names against the SDK version you use.
• Free Speedchecker mode requires location permission and data-sharing behavior defined by Speedchecker.
• Real speed tests are network-intensive and should be user-initiated.

References

• Speedchecker iOS SDK: https://github.com/speedchecker/speedchecker-sdk-ios
• Speedchecker Android SDK: https://github.com/speedchecker/speedchecker-sdk-android
• Speedchecker SDK API docs: https://www.speedchecker.com/products/mobile-apps-and-sdks.html