@volley/vwr-loader

VWR (Volley Web Runtime) loader for Volley TV platform shells (Samsung, LG, Fire TV, etc.).

Features

• Amplitude Flag Fetching: Fetch feature flags from Amplitude Experiment REST API
• Chrome 66+ Compatible: Uses modern browser APIs (Fetch API, async/await, AbortController)
• Safe Defaults: Returns fallback values on error to ensure graceful degradation
• Shell Loader Template: HTML template for shell initialization with VWR integration
• Device ID Resolution: Cross-platform device ID handling

Installation

pnpm add @volley/vwr-loader

Usage

CLI Build (Recommended)

You can build the loader for a specific platform and environment using the CLI. This is useful for native shells (iOS, Android, FireTV, Samsung, LG) and CI/CD pipelines.

# Using npx (if installed globally or in project)
npx build-loader --platform IOS_MOBILE --env dev --output ./dist-ios

# Or via pnpm
pnpm build-loader --platform IOS_MOBILE --env dev --output ./dist-ios

Options:

• --platform: Target platform (IOS_MOBILE, ANDROID_MOBILE, FIRE_TV, SAMSUNG_TV, LG_TV, WEB)
• --env: Environment (local, dev, staging, prod)
• --output: Output directory for index.html and main.js
• --hubUrl: Override Hub URL (optional)
• --vwrUrl: Override VWR URL (optional)
• --amplitudeKey: Override Amplitude deployment key (optional)

Fetching Amplitude Flags

import { fetchAmplitudeFlags } from '@volley/vwr-loader'

const flags = await fetchAmplitudeFlags(
  'device-id-123',
  'samsung',
  {
    apiKey: 'your-amplitude-api-key',
    timeout: 2000
  }
)

console.log(flags['vwr-enabled']) // boolean
console.log(flags['vwr-url'])     // string

Using the VWR Loader Template

The package includes a vwr-loader.html template that can be used as the entry point for platform shells. The template:

1. Fetches feature flags from Amplitude
2. Conditionally loads VWR (Volley Web Runtime) or falls back to legacy Hub
3. Handles device ID resolution across platforms
4. Validates that build-time config was properly injected

Build-time placeholders (must be replaced during build):

• __PLATFORM__ - Platform name (samsung-tv, lg-tv, firetv, etc.)
• __AMPLITUDE_KEY__ - Amplitude deployment key
• __HUB_URL__ - Hub application URL
• __VWR_URL__ - Default VWR bundle URL

CLI: build-loader

The build-loader CLI builds platform-specific VWR loader bundles.

npx build-loader --platform <platform> --output <path> [--env <env>] [options]

Required Options

| Option | Description | |--------|-------------| | --platform | Platform: FIRE_TV, SAMSUNG_TV, LG_TV, MOBILE, WEB | | --output | Output directory path |

Optional Options

| Option | Description | |--------|-------------| | --env | Environment: local, dev, staging, prod | | --hubUrl | Override Hub URL | | --vwrUrl | Override VWR URL | | --configUrl | Override VWR Config URL | | --configFile | Override VWR Config filename | | --amplitudeKey | Override Amplitude deployment key | | --launchUrl | Override launch URL |

Environment Handling

• Fire TV: --env is optional. If omitted, environment is read from native BuildConfig.ENVIRONMENT at runtime. This ensures prod APKs cannot accidentally run dev VWR.
• Other platforms: --env is required since they don't support native environment reading.

Examples

# Fire TV (reads env from native at runtime)
npx build-loader --platform FIRE_TV --output ./www

# Fire TV with env override (for testing)
npx build-loader --platform FIRE_TV --env dev --output ./www

# Samsung TV (env required)
npx build-loader --platform SAMSUNG_TV --env prod --output ./www

Development Commands

# Run tests
pnpm test

# Type checking
pnpm typecheck

# Build
pnpm build

# Lint
pnpm lint

Browser Compatibility

Requires Chrome 66+ or equivalent browser with support for:

• Fetch API
• async/await
• AbortController
• crypto.randomUUID (for fallback device ID generation)

API Reference

fetchAmplitudeFlags(deviceId, platform, config)

Fetches feature flags from Amplitude Experiment using GET method with query parameters.

Parameters:

• deviceId (string): Unique device identifier
• platform (string): Platform name (samsung-tv, lg-tv, firetv, ios, android)
• config (AmplitudeConfig):
  • apiKey (string): Amplitude API key (client-side key starting with "client-")
  • apiUrl (string, optional): API endpoint (defaults to Amplitude production)
  • timeout (number, optional): Request timeout in ms (defaults to 2000)

Returns: Promise<FlagResult>

• vwr-enabled (boolean): Whether VWR should be loaded
• vwr-url (string): VWR bundle URL to load

Error Handling: Returns safe defaults on error:

{
  'vwr-enabled': false,
  'vwr-url': 'https://vwr.volley.tv/v1/vwr.js'
}

VWR Configuration System

The vwr-loader fetches configuration from S3 with a priority-based fallback system. This enables device-specific, shell-version-specific, or environment-specific configurations without rebuilding shells.

Configuration Schema

type VWRConfig = {
    hubUrl: string              // URL to the Hub application
    vwrUrl: string              // URL to the VWR runtime JavaScript file
    launchUrl: string | undefined  // Optional launch URL (defaults to hubUrl)
    trustedDomains: Array<string>  // List of trusted domains for iframe communication
    amplitudeKey: string        // Amplitude API key for analytics
}

Configuration Priority

The loader tries to fetch configs in this order (first successful fetch wins):

1. Local config (development only): http://localhost:5174/vwrConfig.json
2. Device-specific config: {configUrl}/device/{platform}/{deviceId}/vwrConfig.json
3. Shell version config: {configUrl}/shellVersion/{environment}/{platform}/{shellVersion}/vwrConfig.json
4. Environment config: {configUrl}/environments/{environment}/vwrConfig.json
5. Fallback defaults: Built-in defaults from envDefaults.ts

Where configUrl defaults to: https://vwr.volley.tv/config/

S3 Bucket Structure

s3://volley-vwr/config/
├── environments/
│   ├── dev/
│   │   └── vwrConfig.json
│   ├── staging/
│   │   └── vwrConfig.json
│   └── prod/
│       └── vwrConfig.json
├── device/
│   ├── SAMSUNG_TV/
│   │   └── {deviceId}/
│   │       └── vwrConfig.json
│   ├── LG_TV/
│   ├── FIRE_TV/
│   └── WEB/
└── shellVersion/
    └── {environment}/
        └── {platform}/
            └── {version}/
                └── vwrConfig.json

Fetching Config in Shells

import { getVWRConfig } from '@volley/vwr-loader'

const vwrConfig = await getVWRConfig({
    configUrl: 'https://vwr.volley.tv/config/',
    configFile: 'vwrConfig.json',
    platform: 'SAMSUNG_TV',
    deviceId: 'DEVICE123',
    environment: 'prod',
    shellVersion: '1.0.0',
    timeout: 2000  // optional, defaults to 2000ms
})

Default Values

If all config fetches fail, the loader falls back to built-in defaults per environment. See src/envDefaults.ts for current values.

Operations

For S3 config management (uploading, deleting, cache invalidation), see VWR S3 Config Operations.

License

Proprietary - Volley Inc.