# React Native

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

Canonical page: https://anectico.com/docs/instrument/react-native/


`@anectico/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

During early access, install the artifact supplied during onboarding, replacing the path below:

```bash
npm install /path/to/anectico-react-native.tgz
cd ios && pod install
```

After the public npm release, use `npm install @anectico/react-native` instead. Rebuild the native
app after installation; a JavaScript-only reload does not install the native module.

```typescript
import * as Anectico from '@anectico/react-native';

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

await Anectico.identify('user_8842', { plan: 'pro' });
await Anectico.capture('checkout_completed', { total: 42 });
await Anectico.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 Anectico.reset()` on logout. The native reset rotates identity/session,
clears groups, and drops global error-user context plus buffered breadcrumbs so
prior-account diagnostics cannot cross a shared-device logout boundary. Call
`await Anectico.shutdown()` when the runtime is being torn down.

`release`/`serviceVersion` above forward verbatim to the underlying native iOS/Android SDK, which
stamps the reserved `$release`/`$app_version` string properties on every captured event (not only
the automatic `$app_opened`). Neither is invented: omit them and events carry neither property.
See [Reserved event properties](/docs/investigate/event-schema#reserved-properties).

## Errors and crashes

```typescript
try {
  await checkout();
} catch (error) {
  await Anectico.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. Every JavaScript error includes an SDK-owned mechanism:
`rn.captureError` for the public API, `rn.globalHandler` for uncaught errors, or
`rn.unhandledRejection` for rejected promises. On both iOS and Android, Anectico also owns the JavaScript
error's level and handled state: fatal errors are `fatal` / unhandled and other errors are `error` /
handled. Application tags cannot override those classification values. In Release builds, a fatal
global error is persisted synchronously before React Native terminates; Anectico recognizes RN's
immediate native wrapper and shows one frame-accurate JavaScript Issue instead of a duplicate
JavaScript/native pair. Genuine native crashes are still captured by the underlying SDK. If the
synchronous bridge is unavailable or persistence fails, native fallback capture remains enabled so
the error is not lost.

Each occurrence also inherits SDK-owned app/build, OS, and privacy-safe hardware-model context from
the native transport. Anectico never collects a stable device identifier or user-assigned device name.

## 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 `anectico symbols`. Upload the map under its bundle filename
(for example, `index.bundle`, even when the map file is `index.bundle.map`); Anectico automatically
matches Metro frame URLs, including the JSC-safe `index.bundle//&platform=...` spelling, to that
bundle.

## Propagate to your backend

`await Anectico.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.

- [Capture errors and releases](/docs/instrument/errors)
- [React Native SDK API reference](/docs/reference/react-native-sdk)
- [Replay or symbols are not working](/docs/help/replay-and-symbols)