React Native SDK API

Functions, options, parameters, promises, and native behavior for the Teml React Native SDK.

@teml/react-native is a Promise-based JavaScript bridge over the native iOS and Android SDKs. The native layer owns identity, sessions, persistence, network delivery, and native crash handlers; the JavaScript layer adds Hermes/JSC error parsing and global JavaScript error capture.

Use a project key with ingest:write and analytics:write. React Native replay is not supported.

Configure and shut down

import * as Teml from '@teml/react-native';

await Teml.configure({
  apiKey: 'tm_...',
  environment: 'production',
  release: '1.4.0',
  dist: '42',
});

Function	Parameters	Returns	Behavior
`configure(options)`	`TemlOptions`	`Promise<void>`	Configures native SDK state and installs JS error/rejection handlers unless disabled. Native configuration is idempotent.
`flush()`	—	`Promise<void>`	Flushes the native diagnostic-event queue.
`shutdown()`	—	`Promise<void>`	Removes JS/native hooks, flushes, and releases background resources.
`installGlobalErrorCapture()`	—	`void`	Idempotently installs JS global error and unhandled-rejection capture. Normally called by `configure`.

If the native module is unavailable, the bridge resolves safe defaults rather than crashing the application. Rebuild the native application after installing the package; Metro reload cannot add a native module.

`TemlOptions`

Only apiKey is required. Native defaults match the iOS/Android contract.

Option	Type/default	Purpose
`apiKey`	`string`; required	Error/event API key.
`endpoint`	`string`; `https://api.teml.io`	Native API base URL.
`environment`	`string`; `development`	Deployment environment.
`release`, `dist`	optional strings	Release and artifact identifiers.
`serviceName`, `serviceVersion`	optional strings	Native resource identity; defaults from the app.
`flushAt`	`number`; `20`	Event-count flush threshold.
`flushIntervalMs`	`number`; `5000`	Periodic flush; zero disables it.
`maxStackTraceFrames`	`number`; `50`	Native and JS frame cap.
`breadcrumbCapacity`	`number`; `100`	Native ring-buffer capacity.
`maxQueueSize`	`number`; `10000`	Native event queue cap.
`errorSampleRate`	`number`; `1`	Non-fatal error sampling from 0–1.
`enableCrashReporting`	`boolean`; `true`	Install native crash handlers.
`debug`	`boolean`; `false`	Native diagnostic logging.
`enableJsErrorCapture`	`boolean`; `true`	JavaScript-only global error/rejection handlers.

Identity, accounts, and events

Function	Parameters	Returns	Behavior
`identify(distinctId, set?)`	stable ID; person properties	`Promise<void>`	Links anonymous and known identity and queues identify.
`group(type, key, set?)`	account type/key; properties	`Promise<void>`	Records membership and `$groupidentify`.
`capture(event, properties?)`	event; properties	`Promise<void>`	Queues a diagnostic event in native storage.
`screen(name, properties?)`	screen; properties	`Promise<void>`	Queues `$screen` with `$screen_name`.
`reset()`	—	`Promise<void>`	Logout: rotates native identity/session and clears groups.
`getDistinctId()`	—	`Promise<string>`	Current identity, or `""` without native configuration.
`getSessionId()`	—	`Promise<string>`	Current session without extending its idle window, or `""`.

Errors, messages, users, and breadcrumbs

Function	Parameters	Returns	Behavior
`captureError(error, options?)`	`unknown`; `CaptureOptions`	`Promise<string>`	Normalizes the value, parses Hermes/JSC frames, and returns the native error ID.
`captureMessage(message, level?, options?)`	text; `ErrorLevel`; options	`Promise<string>`	Captures a message; `error`/`fatal` receive error status.
`addBreadcrumb(crumb)`	`Breadcrumb`	`Promise<void>`	Adds native trail context for the next error.
`setUser(user)`	`TemlUser`	`Promise<void>`	Sets native global error user context.
`clearUser()`	—	`Promise<void>`	Clears that error user context.

CaptureOptions currently transmits tags and level. Per-capture extra, user, and fingerprint are not supported by this bridge; use setUser for user context. ErrorLevel is debug, info, warning, error, or fatal. A Breadcrumb contains category, message, optional level, and optional data. TemlUser contains id, email, username, ipAddress, and segment.

Global handlers preserve/chains previous React Native handlers. A fatal JavaScript error is marked fatal and bypasses client sampling; native crashes are handled by the underlying platform SDK.

Backend propagation

propagationHeaders(): Promise<Record<string,string>> creates a fresh W3C traceparent and current identity baggage. Add the returned headers only to a trusted, instrumented application backend. They are correlation metadata, not proof of authentication.

Exported stack types

StackFrame is the bridge wire shape: filename, function, lineno, colno, and in_app. Stack normalization/parsing is internal to captureError; applications should not construct raw bridge errors.