---
title: "React Native SDK reference"
description: "TypeScript configuration, client methods, React hooks, callbacks, and purchase integrations."
sidebar:
  label: "React Native"
search:
  tags: ["sdk", "reference", "react-native"]
  keywords: ["Expo", "TypeScript", "React hooks", "configure", "identify", "consumeFeature", "App Action"]
---

The React Native SDK provides a typed client and React hooks for Nuxie's iOS and Android SDKs. Import them from `@nuxie/react-native` after [installing the package](/docs/sdks/react-native).

<span id="interfaces-and-contracts" />

## Configure the client

```typescript
import { nuxie } from '@nuxie/react-native';

await nuxie.configure({
  apiKeys: {
    ios: 'YOUR_IOS_PUBLIC_KEY',
    android: 'YOUR_ANDROID_PUBLIC_KEY',
  },
});
```

You can also pass a configuration to `NuxieProvider`. Its children render during setup; `useNuxieStatus()` reports when the client is `configured`.

### Configuration options

| Option | Default | Description |
| --- | --- | --- |
| `apiKeys` | Required | Public `ios` and `android` app keys. |
| `environment` | `production` | Nuxie service environment: `production` or `development`. |
| `logLevel` | `warning` | `verbose`, `debug`, `info`, `warning`, `error`, or `none`. |
| `localeIdentifier` | Device locale | Locale override, or `null` to use the device locale. |
| `billing` | Native | `{ mode: 'native', handling: 'full' }`, or an external controller. |

Use the public `pk_test_` key for preview content and the `pk_live_` key for live content. Keep the default service environment for both. The development environment selects a separate Nuxie service; it does not select test mode for your app.

Equivalent concurrent `configure()` calls share setup. To change configuration or the external controller, await `shutdown()` before configuring again.

### Client status

`getStatus()` returns an object whose `state` is `unconfigured`, `configuring`, `configured`, or `failed`. Configured status includes `versions.wrapper`, `versions.native`, and `versions.contract`; failed status includes `error`.

`subscribeStatus(listener)` notifies when state changes and returns an unsubscribe function. Read the new value with `getStatus()` in the listener.

## Identify a customer

```typescript
await nuxie.identify('customer_123', {
  properties: { plan: 'pro' },
});
```

Use `getDistinctId()`, `getAnonymousId()`, or `getIsIdentified()` to read identity. Call `reset()` on sign-out to rotate the anonymous ID.

Pass `propertiesSetOnce` to retain an initial customer value. `reset({ keepAnonymousId: true })` preserves the existing anonymous ID; ordinary sign-out should use `reset()`.

### Locale

`await nuxie.setLocaleIdentifier('fr_FR')` overrides the locale. Pass `null` to follow the device. Localized content updates at the next launch or foreground profile synchronization.

## Trigger an Experience

```typescript
await nuxie.trigger('upgrade_requested', { source: 'settings' });
```

The Promise resolves after native invocation. Presentation depends on the published trigger, audience, and re-entry rules. `dismiss()` closes the current presentation.

## Read feature access

```typescript
import { useFeature } from '@nuxie/react-native';

const { state, access } = useFeature('premium-export');
```

Call the hook inside a React component. It updates when access changes, so a purchase can unlock the UI without remounting the screen. Show loading while `state` is `unknown`; read `access?.allowed` to decide whether to enable the feature. `useFeatures()` returns the full snapshot.

For an explicit query, use `hasFeature('premium-export', { policy: 'remote' })`. Queries can include `requiredBalance` and `entityId` and do not consume usage.

### Access values and query options

| Field | Description |
| --- | --- |
| `allowed` | Whether the requested access is available. |
| `unlimited` | Whether usage has no fixed allowance. |
| `balance` | Remaining numeric balance, or `null` when absent. |
| `type` | `boolean`, `metered`, or `creditSystem`. |

`hasFeature()` accepts `requiredBalance` (default `1`), `entityId`, and `policy` (`cacheFirst` or `remote`). An entity query uses grants assigned to that entity. It does not overwrite the global hook snapshot.

The full snapshot from `getFeatures()` or `useFeatures()` contains `all`, `state`, `identityGeneration`, and `revision`. State is `unknown`, `reconciling`, or `ready`; `reconciling` means purchase access is being synchronized. Generation and revision are decimal strings. `subscribeFeatures(listener)` returns an unsubscribe function and notifies when the snapshot changes.

## Consume usage

```typescript
const receipt = await nuxie.consumeFeature('credits', {
  quantity: 5,
  operationId: 'generation_123',
});

if (receipt.accepted) {
  // Start the generation once.
}
```

Reuse the operation ID when retrying the same action. Check `accepted`, even if the remaining `balance` is zero. Your app is responsible for performing the accepted action only once.

### Consumption result

| Field | Description |
| --- | --- |
| `accepted`, `code` | Whether consumption committed and its result code. |
| `operationId`, `quantity` | The action and amount submitted. |
| `balance`, `unlimited`, `active` | Access after the operation. An accepted last use can leave `active: false`. |
| `idempotentReplay` | The result was already recorded for this operation ID. |

Quantities and required balances must be positive integers up to `Number.MAX_SAFE_INTEGER`. Reusing an operation ID with a different command fails. For shared credits, use the credit feature's key and the cost in credit units.

## Purchases and restore

Native billing is the default. For provider checkout, pass `billing: { mode: 'external', controller }`, where `controller` implements:

| Method | Return value |
| --- | --- |
| `purchase(product)` | `Promise<PurchaseResult>`: `purchased`, `cancelled`, `pending`, or `failed` with a `message`. |
| `restorePurchases()` | `Promise<RestoreResult>`: `restored`, `noPurchases`, or `failed` with a `message`. |

The result is an object such as `{ type: 'purchased' }`. Open checkout with the supplied `StoreProduct`, preserving its product, base plan, purchase option, offer, placement, and eligibility values. Return a failure if your provider cannot honor the selected terms. The outcome does not itself establish a credit balance.

`await nuxie.restorePurchases()` invokes the configured restore integration. Read the returned `type` to distinguish no purchases from failure.

Native billing can also use `billing: { mode: 'native', handling: 'observer' }` when the app owns transaction finishing. External billing delegates checkout and finishing to your provider; feature access follows native or connected-provider synchronization.

### Product fields

`StoreProduct` includes `platform`, `productId`, `storeProductId`, `basePlanId`, `purchaseOptionId`, `offerId`, `placementId`, `displayName`, `description`, `displayPrice`, `productType`, `period`, `periodCount`, `billingPlan`, `eligibilityJws`, `pricingPhases`, and `introductoryTerms`. Platform-specific and unavailable fields are `null`. Keep eligibility tokens out of logs.

## Receive App Actions

`onAppAction(listener)` connects an Experience to your app's own behavior, such as navigating to the library after onboarding. It receives the action name and payload and returns an unsubscribe function. React components can use `useNuxieAppAction(handler)` to manage the subscription automatically. `onActivity()` and `useNuxieActivity()` provide activity notifications.

An App Action contains `name`, optional `payload`, and `experience` with `experienceId`, `experienceVersion`, and `journeyId`. Activity includes `id`, `schemaVersion`, `name`, `timestampMs`, `receivedAtMs`, and `properties`. These are live notifications, not a per-trigger completion result.

## React integration

| API | Use |
| --- | --- |
| `NuxieProvider` | Optional `client`, `configuration`, `onActivity`, `onAppAction`, and `onError`. |
| `useNuxie()` | Current provider client, or the process singleton. |
| `useNuxieStatus()` | Setup state and versions. |
| `useFeature(id)` | One stable feature selection. |
| `useFeatures()` | Full feature snapshot. |
| `useNuxieActivity(handler)` | Activity subscription with automatic cleanup. |
| `useNuxieAppAction(handler)` | App Action subscription with automatic cleanup. |

The provider can receive a `NuxieClient` test double. Unmounting removes observers but does not shut down the SDK or reset the customer.

### Event values

Event properties and identity attributes use `JsonObject`: string keys with strings, finite numbers, Booleans, null, arrays, or nested objects. Do not pass functions, class instances, or cyclic structures. Reserve event names beginning with `$` for SDK system events.

## Errors and shutdown

Operations reject with `NuxieError`, an `Error` carrying a stable `code` and the native cause where available. Invalid arguments reject before the native call. A query arriving after the customer changes rejects as stale rather than applying access to another customer.

Catch rejected operations in the calling code. `onError(listener)` observes SDK errors and returns an unsubscribe function; it does not replace Promise error handling.

`await nuxie.shutdown()` tears down the native connection and clears client state. Dispose subscriptions owned by screens when those screens unmount. A timeout or teardown does not undo an already accepted consumption; reconcile it using the original operation ID.

<span id="shared-platform-behavior" />

See [Features and entitlements](/docs/monetization/features-and-entitlements) to configure access, or the [complete API reference](https://github.com/nuxieai/nuxie-react-native/blob/main/docs/api-reference.md) for result types, errors, and lifecycle methods.