@ludeo/unit-player-infra-package

v1.28.4

Published

12 hours ago

Ludeo Unit Player Infra Example - Infrastructure package for game streaming and playable ads

Downloads

2,043

0High
0Medium
0Low

Ludeo Infrastructure Package Template

A template repository containing the Ludeo Unit Player example - a fully workable infrastructure package for game streaming and playable ads, designed to work seamlessly via CDN and provide a single-file solution for interactive gaming experiences.

🎮 Overview

The Ludeo Unit Player is the core interactive component of our gaming platform, representing a playable, shareable slice of a game exposed via cloud streaming. It encapsulates the entire user experience and system logic for a single Ludeo instance.

Key Features

Cloud Streaming: WebRTC-based game streaming with low latency
CDN Ready: Single-file UMD and ES module builds
MRAID Compatible: Full support for mobile rich media ads
Cross-Platform: Works in browsers, React, Vue, and vanilla JS
Real-time State Management: Live connection and game state updates
Production Ready: Fully tested and optimized for production use

🚀 Quick Start

CDN Integration (Recommended)

<!DOCTYPE html>
<html>
<head>
    <title>Ludeo Unit Player</title>
    <link rel="stylesheet" href="https://cdn.ludeo.com/unit-player.css">
</head>
<body>
    <div id="game-container"></div>
    
    <script src="https://cdn.ludeo.com/unit-player.umd.js"></script>
    <script>
        const player = new LudeoUnit.unitPlayer();
        
        player.init({
            userId: 'user-id',
            ludeoId: 'ludeo-id',
            environment: 'staging'
        })
            .then(() => player.actions.startAndPlay('ludeo-id', 'game-id'))
            .catch(console.error);
    </script>
</body>
</html>

NPM Installation

npm install @ludeo/ludeo-infra-package

import { unitPlayer } from '@ludeo/ludeo-infra-package';

const player = new unitPlayer();
await player.init({
    userId: 'user-id',
    ludeoId: 'ludeo-id',
    environment: 'staging'
});
await player.actions.startAndPlay('ludeo-id', 'game-id');

📦 Build Outputs

UMD Build (CDN Ready)

File: dist/unit-player.umd.js
Size: ~500KB (gzipped)
Global: window.LudeoUnit
Use Case: CDN, playable ads, vanilla JS

ES Module Build

File: dist/unit-player.es.js
Size: ~450KB (gzipped)
Import: ES6 modules
Use Case: Modern bundlers, React, Vue

TypeScript Definitions

File: dist/index.d.ts
Use Case: TypeScript projects, IDE support

🎯 Use Cases

1. Playable Ads (MRAID)

Perfect for mobile rich media advertisements with full MRAID support:

<!-- See examples/playable-ad.html for complete example -->
<script src="https://cdn.ludeo.com/unit-player.umd.js"></script>
<script>
    // MRAID integration
    mraid.addEventListener('ready', () => {
        const player = new LudeoUnit.unitPlayer();
        // Initialize and play
    });
</script>

2. React Integration

import React, { useEffect, useRef } from 'react';
import { unitPlayer } from '@ludeo/ludeo-infra-package';

const LudeoPlayer = ({ ludeoId, gameId, userId }) => {
    const containerRef = useRef(null);
    const playerRef = useRef(null);
    
    useEffect(() => {
        const player = new unitPlayer();
        playerRef.current = player;
        
        player.init({
            userId,
            ludeoId,
            environment: 'staging'
        })
            .then(() => player.actions.startAndPlay(ludeoId, gameId))
            .catch(console.error);
            
        return () => player.cleanup();
    }, [ludeoId, gameId, userId]);
    
    return <div ref={containerRef} id="game-container" />;
};

3. Vue.js Integration

<template>
    <div ref="gameContainer" id="game-container"></div>
</template>

<script>
import { unitPlayer } from '@ludeo/ludeo-infra-package';

export default {
    async mounted() {
        this.player = new unitPlayer();
        await this.player.init({
            userId: this.userId,
            ludeoId: this.ludeoId,
            environment: 'staging'
        });
        await this.player.actions.startAndPlay(this.ludeoId, this.gameId);
    },
    beforeUnmount() {
        if (this.player) this.player.cleanup();
    }
};
</script>

🛠️ Development

Prerequisites

Node.js 22.14.0+
npm 10+

Local Development

Quick Start

# 1. Install dependencies
npm install

# 2. Build the project
npm run build

# 3. Serve the built files
npm run preview

# 4. In another terminal, serve the examples
cd examples
npx serve .

# 5. Open your browser to test the examples
# Examples will be available at: http://localhost:3000/playable-ad.html

Development Server

# Start development server (for development)
npm run dev

# Run tests
npm test

# Build for CDN
npm run build:cdn

Project Structure

src/
├── services/           # Core services and utilities
│   ├── api/           # API client and endpoints
│   ├── config/        # Configuration management
│   ├── core-services/ # Core streaming and player services
│   ├── analytics/     # Analytics and tracking
│   └── virtualGamepad/ # Virtual gamepad support
├── App.tsx            # Main application component
└── main.tsx           # Application entry point

🔧 Configuration

Environment Variables

VITE_ENVIRONMENT: staging | production
VITE_API_BASE_URL: API endpoint URL
VITE_CDN_BASE_URL: CDN base URL for assets

Player Configuration

const config = {
    environment: 'staging', // or 'production'
    userId: 'your-user-id',
    ludeoId: 'your-ludeo-id',
    gameId: 'your-game-id',
    challengeId: null, // optional
    debug: false // enable debug logging
};

📊 API Reference

unitPlayer Class

Methods

init(options) - Initialize player
- options.userId - User identifier (required)
- options.ludeoId - Ludeo identifier (required)
- options.challengeId - Challenge identifier (optional)
- options.environment - Environment: 'staging' | 'production' (required)
- options.featureFlagsConfig - Feature flags configuration (optional)
- options.rttThresholdsConfig - Latency thresholds configuration (optional)
subscribe(callback) - Subscribe to state changes
getState() - Get current state
cleanup() - Clean up resources

Actions

actions.startAndPlay(ludeoId, gameId) - Start and play ludeo
actions.stop() - Stop current session
actions.pause() - Pause game
actions.resume() - Resume game

State Object

interface PlayerState {
    stream: {
        connectionState: 'disconnected' | 'connecting' | 'connected' | 'error';
        cloudSessionId?: string;
        networkState?: 'EXCELLENT' | 'GOOD' | 'FAIR' | 'POOR';
    };
    ludeoPlayer: {
        ludeoState: 'idle' | 'loading' | 'playing' | 'paused' | 'ended';
    };
    error?: string;
}

🧪 Testing

Unit Tests

npm test                    # Run all tests
npm run test:watch         # Watch mode
npm run test:coverage      # Coverage report

E2E Tests

npm run e2e:local         # Local testing
npm run e2e:prod          # Production testing
npm run e2e:headed        # Headed browser testing

Playwright MCP Test

For comprehensive connection testing, use the Playwright MCP test:

Navigate to http://localhost:5173/be44fd20-9155-4880-8364-a4750846b7f5?newUnit=true
Follow the step-by-step validation in tests/ludeoUnitMCPTest.md

🚀 Deployment

CDN Deployment

Build the package: npm run build:cdn
Upload dist/ files to your CDN
Configure CORS headers
Set up caching strategy

NPM Publishing

npm run build
npm publish

📈 Performance

Bundle Analysis

npm run build:analyze

Optimization Features

Tree shaking for ES modules
Code splitting for better caching
Gzip compression support
Lazy loading capabilities

🔒 Security

Content Security Policy

<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; 
               script-src 'self' https://cdn.ludeo.com; 
               connect-src 'self' https://services.stg.use1.ludeo.com;">

CORS Configuration

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Headers: Content-Type

🐛 Troubleshooting

Common Issues

CORS Errors: Ensure CDN has proper CORS headers
Script Loading: Check network tab for 404 errors
Global Variable: Verify window.LudeoUnit is available
Connection Issues: Check proxy server and authentication

Debug Mode

const player = new LudeoUnit.unitPlayer();
player.setDebugMode(true);

📚 Examples

Running the Examples

To test the Ludeo Unit Player examples locally:

Build the project first:
```
npm run build
```
Serve the built files:
```
npm run preview
```
This serves the built files on http://localhost:5001
In another terminal, serve the examples:
```
cd examples
npx serve .
```
This serves the examples on http://localhost:3000
Open the examples in your browser:
- Playable Ad Example: http://localhost:3000/playable-ad.html
- The example will load the UMD bundle from the preview server

Available Examples

examples/playable-ad.html - Complete MRAID playable ad example
CDN_USAGE.md - Comprehensive CDN integration guide
tests/ - Test examples and validation scripts

🤝 Contributing

This is a template repository containing the Ludeo Unit Player example. To use this template:

Use as Template: Click "Use this template" to create your own repository
Customize: Modify the player implementation for your specific needs
Deploy: Build and deploy your customized version
Contribute Back: Submit improvements to the template via pull requests

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Run tests: npm run commit-check
Submit a pull request

📄 License

🆘 Support

Documentation: CDN_USAGE.md
Issues: GitHub Issues
Support: [email protected]

Version: 2.24.6
Last Updated: December 2024