React Native SDK reference

TypeScript configuration, client methods, React hooks, callbacks, and purchase integrations.

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.

Configure the client

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

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

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

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

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

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

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

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:

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

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.

See Features and entitlements to configure access, or the complete API reference for result types, errors, and lifecycle methods.