AssetFlux React Native SDK

Manage, version, and deliver remote images to your React Native applications in real time — no app store review required.

Getting Started

1. Install

npm install @assetflux.io/react-native @react-native-async-storage/async-storage
# iOS only
cd ios && pod install

2. Initialize

import { AssetFlux } from '@assetflux.io/react-native';

await AssetFlux.init({
  projectId: 'af_your_project_id',
  apiKey: 'afk_your_sdk_key',
});

3. Display a Remote Asset

import { RemoteImage } from '@assetflux.io/react-native';

<RemoteImage assetKey="home.hero.banner" width={300} height={200} />

Usage

RemoteImage Component

import { RemoteImage, ShimmerPlaceholder } from '@assetflux.io/react-native';

// With shimmer placeholder and fallback
<RemoteImage
  assetKey="home.hero.banner"
  placeholder={<ShimmerPlaceholder width={300} height={200} borderRadius={8} />}
  errorWidget={<Text>Failed to load</Text>}
  fallbackSource={require('./assets/fallback.png')}
  resizeMode="cover"
  width={300}
  height={200}
  fadeInDuration={300}
/>

Prefetch

await AssetFlux.prefetch('home.hero.banner');
await AssetFlux.prefetchAll(['home.logo', 'home.banner']);
await AssetFlux.prefetchPattern('home.*');

Direct URL Resolution

const url = await AssetFlux.resolveAssetUrl({
  assetKey: 'home.banner',
  devicePixelRatio: 3.0,
});

Debug Info

const info = await AssetFlux.getDebugInfo('home.hero.banner');
console.log(info);

Configuration

import { FallbackMode, IdentifierType } from '@assetflux.io/react-native';

await AssetFlux.init({
  projectId: 'af_...',
  apiKey: 'afk_...',
  config: {
    cacheTTL: 24 * 60 * 60 * 1000,       // 24 hours
    refreshInterval: 15 * 60 * 1000,      // 15 minutes
    timeout: 10_000,                       // 10 seconds
    retryAttempts: 3,
    fallbackBehavior: FallbackMode.CacheFirst,
    identifierType: IdentifierType.Device,
    debug: false,
  },
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | cacheTTL | number | 86400000 (24h) | Manifest cache TTL in ms | | refreshInterval | number | 900000 (15m) | Background refresh interval in ms | | timeout | number | 10000 (10s) | Network request timeout in ms | | retryAttempts | number | 3 | Max retry attempts with exponential backoff | | fallbackBehavior | FallbackMode | CacheFirst | Offline behavior strategy | | identifierType | IdentifierType | Device | Identifier for rollout assignment | | customIdentifier | string? | — | Custom identifier value | | instanceConfig | InstanceConfig? | — | Custom API instance ({ baseUrl }) | | debug | boolean | false | Enable debug logging |

Fallback Modes

| Mode | Behavior | |------|----------| | CacheFirst | Serve cached manifest even if stale, refresh in background | | Bundled | Fall back to bundled assets when offline | | Placeholder | Show placeholder component on failure |

Gradual Rollout

Users are deterministically assigned to rollout buckets (0–99) using SHA-256 hashing. The same user always sees the same variant.

// Device-based (default) — persistent across app restarts
{ identifierType: IdentifierType.Device }

// User-based — set after login
{ identifierType: IdentifierType.User }
AssetFlux.setUserId('user_12345');

// Custom identifier
{ identifierType: IdentifierType.Custom, customIdentifier: 'org_abc' }

Reactive Rebuilds

RemoteImage automatically re-renders when the manifest updates:

// Or subscribe manually
const unsubscribe = AssetFlux.addManifestListener(() => {
  console.log('Manifest updated');
});

Requirements

• React Native >= 0.70
• React >= 18.0
• iOS 13+ / Android API 21+

Documentation

Full documentation is available at docs.assetflux.io/react-native.

License

BSD 3-Clause. See LICENSE for details.