SDK reference

@perfbitapp/rn-sdk exports a single object, PerfSDK. There are no hooks, no provider component and no manual instrumentation API — configuration happens once, in init().

Exports

import { PerfSDK } from '@perfbitapp/rn-sdk';
import type { PerfSDKConfig, QueuedEvent } from '@perfbitapp/rn-sdk';

PerfSDK is a singleton instance, not a class — you do not construct it.

PerfSDK.init(config)

Starts every tracker and begins the flush timer. Call it once, as early as possible in your entry file. A second call logs a warning and returns without doing anything.

interface PerfSDKConfig {
  apiKey: string;
  appVersion: string;
  environment?: 'development' | 'staging' | 'production';
  debug?: boolean;
  endpoint?: string;
  navigationRef?: React.RefObject<unknown>;
}

Options

Option	Type	Default	Description
apiKey*	string	—	Your app's key, from onboarding or Settings → API Key. It identifies which app the events belong to.
appVersion*	string	—	The version this build reports. Free-form, but it becomes the build dimension in the dashboard, so it should change when you ship.
environment	'development' \| 'staging' \| 'production'	'production'	Tags every event. Only `production` data is shown in the dashboard — see the warning below.
debug	boolean	false	Logs SDK activity to the console under `[perfbit]`, and is required to enable tracking when `environment` is `'development'`.
endpoint	string	'https://perfbit.app/api/ingest'	Override where batches are posted. Useful for pointing a development build at a local server.
navigationRef	React.RefObject<unknown>	—	Your React Navigation container ref. Screen tracking is disabled without it — see Screen tracking.

Two environment gotchas

1. environment: 'development' disables the SDK unless debug: true is also set. init() returns early and no trackers start. It logs [PerfSDK] Tracking disabled in development mode. Pass debug: true to enable.

2. Only production events reach the dashboard. Events tagged staging or development are validated, accepted and stored, but every dashboard query filters to production — so a staging build will look like it is sending nothing.

PerfSDK.flush()

Sends everything currently queued and resolves when the request settles. Batching already flushes on a timer and on backgrounding, so you rarely need this — it is mainly useful in tests or just before a deliberate app termination.

// Force a send instead of waiting for the next 30s interval
await PerfSDK.flush();

It never rejects. A failed send is re-queued internally rather than surfaced as an error.

PerfSDK.getConfig() and PerfSDK.isInitialized()

getConfig() returns the config object you passed, or null if init() has not run (or bailed out in development mode). isInitialized() returns a boolean for the same condition. Both are read-only helpers — there is no way to reconfigure a running SDK.

Batching and delivery

Events go into an in-memory queue as they are produced. The queue flushes when any of these happens:

Every 30 seconds, on a timer started by init().
At 50 queued events, immediately.
On backgrounding, when AppState changes to background.
On an unhandled JS error, so crash events are not lost to the process dying.
When you call flush().

A batch is one POST with a 10-second timeout. If it fails, the events are put back at the head of the queue and retried on the next flush, up to 3 times; after that the batch is dropped so a persistent outage cannot grow the queue without bound.

Note

The queue is in memory only — it is not persisted to disk. Events produced since the last flush are lost if the app is force-killed. This is also why the first data can take up to 30 seconds to appear.

Self-hosting the ingest endpoint

endpoint accepts any URL that speaks the ingestion API contract:

PerfSDK.init({
  apiKey: 'YOUR_API_KEY',
  appVersion: '1.0.0',
  endpoint: 'https://perf.example.com/api/ingest',
});

Overhead

The trackers are JavaScript-only. Frame sampling runs a requestAnimationFrame loop and aggregates counters, reporting once per 10-second window rather than per frame. Network tracking wraps fetch and XMLHttpRequest and records timings around the original call — it does not buffer or inspect bodies.