AI Coding Agents: STOP. Read AGENTS.md in full before writing a single line of code. It is your only source of truth.

Conviva Custom App Analytics SDK — Amazon Kepler / VegaOS Adapters

Companion adapter package for the Conviva Custom App Analytics SDK targeting Amazon Kepler / VegaOS React Native apps (Fire TV Vega devices).

This package provides VegaOS-runtime implementations of the three platform adapter interfaces required by the SDK: HttpTransport, StorageAdapter, TimerAdapter.

The same UMD bundle (conviva-js-custom-app-analytics-sdk-vegaos-adapters.umd.min.js) is published to NPM and to Conviva's CDN.

Installation

NPM

npm install @convivainc/conviva-js-custom-app-analytics-sdk \
            @convivainc/conviva-js-custom-app-analytics-sdk-vegaos-adapters

You also need @amazon-devices/react-native-async-storage__async-storage installed (Amazon's AsyncStorage implementation — provided by every Kepler RN app).

Script Tag (uncommon for React Native)

React Native apps don't typically load JavaScript via <script> tags. Script-tag use of this package is rare. If your host environment loads scripts directly, the CDN URL pattern is:

<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk-vegaos-adapters.umd.min.js"></script>

The script exposes the global convivaCustomTrackingVegaOSAdapters.

Usage

NPM / ES Modules

import { convivaAppTracker } from '@convivainc/conviva-js-custom-app-analytics-sdk';
import { createVegaOSAdapters } from '@convivainc/conviva-js-custom-app-analytics-sdk-vegaos-adapters';

// IMPORTANT: createVegaOSAdapters() is async — it pre-hydrates AsyncStorage
const adapters = await createVegaOSAdapters();

convivaAppTracker({
  appId: 'YOUR_APP_NAME',
  convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
  appVersion: '1.0.0',
  ...adapters,
});

Why is the factory async? React Native AsyncStorage is asynchronous, but the tracker reads identity (clid, iid) synchronously during init. The factory pre-hydrates all Conviva*-prefixed and convivaOutQueue_*-prefixed keys into a synchronous in-memory cache, then exposes a sync StorageAdapter over that cache.

What's exported

| Export | Purpose | |---|---| | createVegaOSAdapters() | Async convenience factory — returns all three adapters with AsyncStorage pre-hydrated | | createVegaOSHttpTransport(fetchImpl?) | HTTP adapter alone (wraps globalThis.fetch or an injected FetchLike) | | createVegaOSStorageAdapter(asyncStorage) | Storage adapter alone — caller is responsible for hydration | | createVegaOSTimerAdapter() | Timer adapter alone (wraps standard JS timer globals) |

Use createVegaOSAdapters() unless you have a reason to manage hydration yourself.

Behaviour notes

• HTTP errors degrade silently. sendRequest resolves with { status: 0 } on any failure (network error, fetch reject, AbortController timeout). Never throws.
• Storage failures degrade silently. Reads return null; writes/removes are no-ops on failure.
• Timers are wrapped in try/catch. setTimeout / setInterval return 0 on failure.
• Async-init contract. createVegaOSAdapters() is async because it pre-hydrates Conviva-owned storage keys (Conviva* and convivaOutQueue_* prefixes) from React Native AsyncStorage into a synchronous in-memory cache. You must await the factory before calling convivaAppTracker(...) — the tracker reads identity, RC cache, event queue, and sampling random number during its synchronous init path.

Implementing your own adapter

If you need to customize behaviour beyond what createVegaOSAdapters() provides — for example, a custom HTTP transport, a different pre-hydration strategy, or a non-AsyncStorage backing — implement the adapter interfaces directly and pass them to the main SDK. The three interfaces (HttpTransport, StorageAdapter, TimerAdapter) and a full example are documented in the parent SDK README's Custom Adapters section. The StorageAdapter interface is synchronous — if you swap in another async storage backend, replicate the same boot-time pre-hydration pattern that createVegaOSAdapters() uses.

Versioning

This package is intended to be used alongside @convivainc/conviva-js-custom-app-analytics-sdk. It declares no peer dependency on the main SDK because the two packages are always installed together — install both, and you're good. The only declared peer dependency is @amazon-devices/react-native-async-storage__async-storage, which is provided by every Kepler / VegaOS app.

See CHANGELOG.md for version history.