Browse documentation

Instrument

React Native

Connect JavaScript and native mobile failures to one React Native customer journey.

@teml/react-native is a thin bridge over the native iOS and Android SDKs. It shares their identity, session, event queue, native crash handling, and retry behavior while adding JavaScript error capture. React Native 0.73 and later is supported through the NativeModule interoperability layer.

Install and configure

npm install @teml/react-native
cd ios && pod install

During early access, install the artifact or repository path supplied during onboarding.

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

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

await Teml.identify('user_8842', { plan: 'pro' });
await Teml.capture('checkout_completed', { total: 42 });
await Teml.screen('Checkout');

Use a project-scoped key with ingest:write and analytics:write. Do not include read, management, or agent scopes in the application.

Call await Teml.reset() on logout and await Teml.shutdown() when the runtime is being torn down.

Errors and crashes

try {
  await checkout();
} catch (error) {
  await Teml.captureError(error, { tags: { screen: 'Checkout' } });
}

configure installs handlers for uncaught JavaScript errors and unhandled promise rejections unless enableJsErrorCapture is false. The previous handlers remain chained, so React Native’s normal error and crash behavior continues. Native crashes are captured by the underlying SDK.

Upload all release artifacts

A release build can need more than one artifact:

  • Metro source maps for JavaScript frames;
  • an iOS dSYM for native iOS frames; and
  • Android mapping.txt for R8/ProGuard frames.

Use the same release and dist used at configuration. Upload Metro source maps with the JavaScript source-map uploader and native files with teml symbols.

Propagate to your backend

await Teml.propagationHeaders() returns traceparent and baggage. Add them only to requests sent to a trusted, instrumented backend. Do not add customer identity baggage to third-party endpoints.

Verify

Capture one caught JavaScript error and one native test event for an identified test user. Confirm both appear under that customer. If the native module is unavailable, rebuild the application after installing pods or Gradle dependencies; a Metro refresh alone cannot add native code.