react-native-adaxon

React Native / Expo SDK for event tracking and offer recommendations.

Dependencies: react and react-native only. The SDK does not bundle AsyncStorage, NetInfo, or other storage/network libraries.

Install

Production

npm install react-native-adaxon
# or
yarn add react-native-adaxon
# or
npx expo install react-native-adaxon

Testing / staging

npm install react-native-test-adx

Both packages expose the same public API.

Quick start

import { AdaxonProvider, useAdaxon } from 'react-native-adaxon';
import { Button, Text } from 'react-native';

export default function App() {
  return (
    <AdaxonProvider
      configuration={{
        appId: 'adx_your_app_id',
        sdkKey: 'your_sdk_key',
        testMode: __DEV__,
      }}
    >
      <HomeScreen />
    </AdaxonProvider>
  );
}

function HomeScreen() {
  const { isInitialized, initializationError, logEvent } = useAdaxon();

  if (!isInitialized) {
    return <Text>{initializationError ?? 'Initializing…'}</Text>;
  }

  return (
    <Button
      title="Track event"
      onPress={() => logEvent('level_completed', { level_number: 10 })}
    />
  );
}

Tracking calls do not update React state, so logEvent and track will not re-render your app.

AdaxonProvider is required for full-screen ads (showAd).

Configuration

Pass configuration to AdaxonProvider, or to Adaxon.initialize() when not using React.

| Field | Required | Default | Description | |---|---|---|---| | appId | Yes | — | Your MTS app id (adx_…) | | sdkKey | Yes | — | Sent as the x-sdk-key header | | storage | No | In-memory | Persists offline event queue and anonymous id | | timeoutMs | No | 10000 | HTTP timeout in ms | | testMode | No | false | Sets sdk_version to {version}-test when true | | activityLogging | No | false | When true, records SDK diagnostics to Sentry (testing/debugging) | | sentryDsn | No | — | Sentry DSN when activityLogging is true and the host app has not initialized Sentry |

Only appId and sdkKey are required. Do not pass a tracker URL — the SDK owns the host and API paths.

For Sentry activity logging, install the optional peer dependency @sentry/react-native in the host app.

Activities are emitted primarily as Sentry structured logs (enableLogs: true when the SDK initializes Sentry). Breadcrumbs are added only for warn/error to enrich captured issues. If structured logging is unavailable (for example an older host Sentry client), a small set of milestone activities may use captureMessage instead so they still appear independently without flooding issue volume.

The SDK attaches device, app, user.anonymous_id, and network fields automatically. Do not pass them in event calls.

Persistent storage (optional)

By default the SDK uses in-memory storage. Offline events and the anonymous id are lost when the app closes.

Pass any object that implements AdaxonStorageAdapter:

<AdaxonProvider
  configuration={{
    appId: 'adx_your_app_id',
    sdkKey: 'your_sdk_key',
    storage: {
      getItem: (key) => myKeyValueStore.get(key),
      setItem: (key, value) => myKeyValueStore.set(key, value),
      removeItem: (key) => myKeyValueStore.delete(key),
    },
  }}
>
  {/* … */}
</AdaxonProvider>

Public API reference

Everything below is exported from react-native-adaxon / react-native-test-adx via src/index.ts.

React apps: use AdaxonProvider + useAdaxon().

Non-React apps: use the Adaxon singleton (AdaxonSdk.shared).

AdaxonProvider

Initializes the SDK when the app mounts and mounts the interstitial overlay for ads.

import { AdaxonProvider } from 'react-native-adaxon';

<AdaxonProvider
  configuration={{ appId: 'adx_your_app_id', sdkKey: 'your_sdk_key' }}
  listener={{
    onInitializationComplete: () => console.log('Adaxon ready'),
    onInitializationFailed: (code, message) =>
      console.warn('Adaxon init failed', code, message),
  }}
>
  {/* your app */}
</AdaxonProvider>

| Prop | Required | Description | |---|---|---| | configuration | Yes | SDK credentials and optional settings | | listener | No | Init success/failure callbacks | | children | Yes | App content |

useAdaxon()

Hook that returns init status and all tracking, queue, and ad methods. Must be used inside AdaxonProvider.

const adaxon = useAdaxon();

isInitialized

boolean — true after the SDK initializes successfully.

const { isInitialized } = useAdaxon();

if (!isInitialized) {
  return <Text>Loading…</Text>;
}

initializationError

string | null — error message when initialization failed; null on success or while initializing.

const { isInitialized, initializationError } = useAdaxon();

if (!isInitialized) {
  return <Text>{initializationError ?? 'Initializing…'}</Text>;
}

logEvent(eventName, values?, options?)

Track a custom event. values are normalized to event properties.

const { logEvent } = useAdaxon();

await logEvent('level_completed', { level_number: 10, coins_used: 50 });

Event names must match ^[a-zA-Z][a-zA-Z0-9_]*$ and be at most 100 characters.

track(eventName, properties?, options?)

Send one event immediately when online. When offline, the event is queued automatically.

const { track } = useAdaxon();

await track('button_clicked', { button_name: 'checkout' });

trackBatch(events)

Send 1–100 events in one request when online. When offline, events are queued automatically.

const { trackBatch } = useAdaxon();

await trackBatch([
  { eventName: 'screen_view', properties: { screen: 'home' } },
  { eventName: 'screen_view', properties: { screen: 'settings' } },
]);

enqueueEvent(eventName, properties?, options?)

Store an event locally without sending it. Use processPendingEvents() to flush the queue.

const { enqueueEvent } = useAdaxon();

await enqueueEvent('level_completed', { level_number: 10 });

processPendingEvents()

Flush queued events in FIFO order, up to 100 per batch. Returns a BatchProcessResult.

const { processPendingEvents } = useAdaxon();

const result = await processPendingEvents();
// result.status: 'completed' | 'stopped' | 'already_processing'
// result.eventsProcessed, result.batchesSent, result.failedQueueIds

When the device is offline, track, trackBatch, and logEvent queue events automatically. When connectivity returns, pending events flush in the background. On startup, pending events also flush when the network is available.

trackPurchase(params, options?)

Track a purchase event (AdxEvent.PURCHASE). Maps amount → adx_revenue, currency → adx_currency, product_id/content_id → adx_content_id.

const { trackPurchase } = useAdaxon();

await trackPurchase({
  order_id: 'ORD123',
  amount: 999,
  currency: 'INR',
  product_id: 'P123',
});

trackAddToCart(params, options?)

Track an add-to-cart event (AdxEvent.ADD_TO_CART). Maps price → adx_revenue, currency → adx_currency, product_id/content_id → adx_content_id.

const { trackAddToCart } = useAdaxon();

await trackAddToCart({
  product_id: 'P123',
  price: 499,
  currency: 'INR',
  quantity: 1,
});

trackLogin(params?, options?)

Track a login event (AdxEvent.LOGIN).

const { trackLogin } = useAdaxon();

await trackLogin({ method: 'email' });

trackCompleteRegistration(params?, options?)

Track a registration event (AdxEvent.COMPLETE_REGISTRATION).

const { trackCompleteRegistration } = useAdaxon();

await trackCompleteRegistration({ method: 'google' });

showAd()

Show the first eligible offer as a full-screen interstitial. Does nothing if no offer is available.

const { showAd } = useAdaxon();

await showAd();

Requires AdaxonProvider for the interstitial overlay.

Interstitial behavior:

• A progress bar runs for about 8 seconds.
• The close (×) button appears after the bar completes.
• Tapping the creative opens offer_url.

Adaxon (imperative API)

Use when React is not available. Exposes the same tracking, queue, and ad methods as useAdaxon(), plus lifecycle helpers.

import { Adaxon } from 'react-native-adaxon';

Adaxon.initialize(configuration, listener?)

Initialize the SDK. Required before any other call.

await Adaxon.initialize({
  appId: 'adx_your_app_id',
  sdkKey: 'your_sdk_key',
  testMode: false,
});

Adaxon.isInitialized()

Returns whether the SDK has been initialized.

if (Adaxon.isInitialized()) {
  await Adaxon.logEvent('app_opened');
}

Adaxon.isNetworkAvailable()

Returns whether the SDK considers the device online.

if (Adaxon.isNetworkAvailable()) {
  await Adaxon.processPendingEvents();
}

Adaxon.destroy()

Tear down the SDK instance. AdaxonProvider calls this automatically on unmount.

Adaxon.destroy();

Tracking, queue, and ads

These methods match useAdaxon():

| Method | Same as | |---|---| | Adaxon.logEvent | useAdaxon().logEvent | | Adaxon.track | useAdaxon().track | | Adaxon.trackBatch | useAdaxon().trackBatch | | Adaxon.enqueueEvent | useAdaxon().enqueueEvent | | Adaxon.processPendingEvents | useAdaxon().processPendingEvents | | Adaxon.trackPurchase | useAdaxon().trackPurchase | | Adaxon.trackAddToCart | useAdaxon().trackAddToCart | | Adaxon.trackLogin | useAdaxon().trackLogin | | Adaxon.trackCompleteRegistration | useAdaxon().trackCompleteRegistration | | Adaxon.showAd | useAdaxon().showAd |

Example without React:

import { Adaxon } from 'react-native-adaxon';

await Adaxon.initialize({
  appId: 'adx_your_app_id',
  sdkKey: 'your_sdk_key',
});

await Adaxon.logEvent('level_completed', { level_number: 10 });
await Adaxon.trackPurchase({ order_id: 'ORD123', amount: 999, currency: 'INR' });
await Adaxon.showAd();

Prefer AdaxonProvider in React Native apps so init state and interstitials work correctly.

Constants

AdxEvent

Predefined event name constants.

import { AdxEvent } from 'react-native-adaxon';

AdxEvent.PURCHASE;              // 'adx_purchase'
AdxEvent.ADD_TO_CART;           // 'adx_add_to_cart'
AdxEvent.LOGIN;                 // 'adx_login'
AdxEvent.COMPLETE_REGISTRATION; // 'adx_complete_registration'

AdxParam

Predefined property name constants used by commerce helpers.

import { AdxParam } from 'react-native-adaxon';

AdxParam.REVENUE;    // 'adx_revenue'
AdxParam.CURRENCY;   // 'adx_currency'
AdxParam.CONTENT_ID; // 'adx_content_id'

Errors

Failed SDK calls throw AdaxonSdkError with a code:

| Code | Meaning | |---|---| | INVALID_CONFIG | Missing or invalid SDK configuration | | VALIDATION_ERROR | Invalid event name, properties, or batch | | AUTHENTICATION_ERROR | Invalid SDK key | | HTTP_ERROR | Server returned an error | | NETWORK_ERROR | Network request failed | | TIMEOUT | Request timed out |

import { AdaxonSdkError } from 'react-native-adaxon';

try {
  await logEvent('invalid name!', {});
} catch (error) {
  if (error instanceof AdaxonSdkError) {
    console.warn(error.code, error.message);
  }
}

Exported types

TypeScript types exported for app integration:

| Type | Use | |---|---| | AdaxonStorageAdapter | Custom persistent storage | | AdaxonSdkConfig | SDK configuration shape | | AdaxonInitializationListener | Init callbacks for AdaxonProvider / Adaxon.initialize | | TrackPurchaseParams | Params for trackPurchase | | TrackAddToCartParams | Params for trackAddToCart | | TrackLoginParams | Params for trackLogin / trackCompleteRegistration | | EventProperties | Event property map (string, number, boolean, null) | | TrackEventInput | Single event in trackBatch | | TrackEventOptions | Optional eventId / eventTime on track calls | | EventIngestionResponse | Response from track calls | | BatchProcessResult | Response from processPendingEvents |

Android

Your Adaxon credential platform must allow Android (android or react_native).

License

MIT