ads-reels-player

v1.4.1

Published

2 months ago

A lightweight, customizable ads and reels video player SDK for modern web applications. Works like Mux with video keys, supports React, Vue, Angular, and vanilla JavaScript. Framework agnostic video player with Mux-like functionality. Browser-only SDK wit

ads-reels-player

A lightweight, customizable ads and reels video player SDK for modern web applications. Works like Mux with video keys, supports React, Vue, Angular, and vanilla JavaScript.

🚀 Quick Start

Installation

npm install ads-reels-player

⚠️ Important: Browser-Only SDK

This SDK requires a browser environment and cannot be used in Node.js. See the Setup Guide for proper usage examples.

Basic Usage (Vanilla JavaScript)

<!DOCTYPE html>
<html>
<head>
    <title>My Video App</title>
</head>
<body>
    <h1>My Website</h1>
    
    <!-- Load the SDK -->
    <script src="https://unpkg.com/ads-reels-player@latest/dist/index.umd.js"></script>
    
    <script>
        // Create a video player
        const player = new window.VideoPlayerSDK({
            key: 'demo-1',  // Use predefined video
            position: 'bottom-right',
            width: '320px',
            height: '480px'
        });
        
        // Initialize the player
        player.init();
    </script>
</body>
</html>

ES Modules (Modern Browsers)

<script type="module">
    import { VideoPlayerSDK } from 'https://unpkg.com/ads-reels-player@latest/dist/index.es.js';
    
    const player = new VideoPlayerSDK({
        key: 'demo-1',
        position: 'bottom-right',
        width: '320px',
        height: '480px'
    });
    
    await player.init();
</script>

Node.js/ES Modules

import { VideoPlayerSDK } from 'ads-reels-player';

const player = new VideoPlayerSDK({
    key: 'demo-1',
  position: 'bottom-right',
  width: '320px',
    height: '480px'
});

await player.init();

📋 Available Predefined Keys

| Key | Title | Description | |-----|-------|-------------| | demo-1 | "Discover Amazing Features - Limited Time Offer" | Promotional video | | demo-2 | "New Collection Launch - Get 20% Off" | Product launch | | demo-3 | "Join Our Community - Exclusive Benefits" | Community building | | video-1 | "Big Buck Bunny" | Sample video 1 | | video-2 | "Elephants Dream" | Sample video 2 | | video-3 | "For Bigger Blazes" | Sample video 3 |

🎯 Usage Examples

Example 1: Predefined Key (Easiest)

const player = new VideoPlayerSDK({
    key: 'demo-1',  // No need to provide video data!
    position: 'bottom-right',
    width: '320px',
    height: '480px'
  });

await player.init();

Example 2: Custom Video Data

const player = new VideoPlayerSDK({
    uniqueId: 'my-video',
  videoData: {
    video: 'https://example.com/video.mp4',
    title: 'My Video Title',
    video_routing_link: 'https://example.com/action',
    button_text: 'Click Here'
  },
  position: 'bottom-right',
  width: '320px',
  height: '480px'
});

await player.init();

Example 3: Multiple Videos with Navigation

const player = new VideoPlayerSDK({
    keys: ['demo-1', 'demo-2', 'demo-3'],  // Multiple videos
    position: 'center',
    width: '350px',
    height: '500px',
    showNavigation: true,  // Enable prev/next buttons
    onVideoChange: (videoData, index) => {
        console.log(`Now playing: ${videoData.title} (${index + 1}/3)`);
    }
});

await player.init();

Example 4: With Callbacks

const player = new VideoPlayerSDK({
    videoData: {
        video: 'https://example.com/video.mp4',
        title: 'Special Offer - 50% Off Today!',
        video_routing_link: 'https://example.com/special-offer',
        button_text: 'Get 50% Off'
    },
    position: 'bottom-left',
    width: '280px',
    height: '420px',
    onClose: () => {
        console.log('User closed the video');
    },
    onNavigate: (url) => {
        console.log('User clicked action button, navigating to:', url);
        window.open(url, '_blank');
    },
    onError: (error) => {
        console.error('Player error:', error);
    }
});

await player.init();

🎨 Positioning Options

position: 'bottom-right'  // Most common
position: 'top-left'
position: 'top-right'
position: 'bottom-left'
position: 'center'
position: 'custom'

🎮 Player Controls

// Initialize
await player.init();

// Navigate videos (for multiple videos)
player.nextVideo();
player.previousVideo();

// Close the player
player.close();

// Update position
player.updatePosition('top-left');

// Update size
player.updateSize('400px', '600px');

// Get current state
const currentVideo = player.getCurrentVideo();
const currentIndex = player.getCurrentIndex();
const videoList = player.getVideoList();

🌐 Framework Support

React

import { VideoPlayerSDK } from 'ads-reels-player';

function MyComponent() {
    const player = new VideoPlayerSDK({
        key: 'demo-1',
        position: 'bottom-right',
        width: '320px',
        height: '480px'
    });
    
    useEffect(() => {
        player.init();
        return () => player.close();
    }, []);
    
    return <div>My Component</div>;
}

Vue

import { VideoPlayerSDK } from 'ads-reels-player';

export default {
    mounted() {
        this.player = new VideoPlayerSDK({
            key: 'demo-1',
            position: 'bottom-right',
            width: '320px',
            height: '480px'
        });
        
        this.player.init();
    },
    beforeUnmount() {
        this.player?.close();
    }
}

Angular

import { VideoPlayerSDK } from 'ads-reels-player';

@Component({...})
export class MyComponent {
    private player?: VideoPlayerSDK;
    
    ngOnInit() {
        this.player = new VideoPlayerSDK({
            key: 'demo-1',
            position: 'bottom-right',
            width: '320px',
            height: '480px'
        });
        
        this.player.init();
    }
    
    ngOnDestroy() {
        this.player?.close();
    }
}

⚠️ Important Notes

Browser-Only SDK

This SDK is designed for browser environments only. It requires DOM APIs and cannot be used in Node.js.

Environment Detection

The SDK automatically detects the environment and will throw a clear error if used in Node.js:

// This will throw an error in Node.js
const player = new VideoPlayerSDK({ key: 'demo-1' });
// Error: ads-reels-player: This SDK requires a browser environment. DOM APIs are not available in Node.js.
// 
// To use this SDK:
// 1. Use it in a browser (HTML file, React, Vue, Angular)
// 2. Import via CDN: <script src="https://unpkg.com/ads-reels-player@latest/dist/index.umd.js"></script>
// 3. Or use ES modules in browser: import { VideoPlayerSDK } from "https://unpkg.com/ads-reels-player@latest/dist/index.es.js"

React Dependencies

React is an optional peer dependency. The SDK works without React, but React-specific features (like hooks) require React to be installed.

Supported Environments

✅ Browser (HTML files) ✅ React applications ✅ Vue applications ✅ Angular applications ✅ Vanilla JavaScript ❌ Node.js (server-side) ❌ Server-side rendering (SSR)

🔧 API Reference

VideoPlayerSDK Constructor

new VideoPlayerSDK(config)

Configuration Options

interface SDKConfig {
    // Video data sources
    key?: string;                    // Single predefined key
    keys?: string[];                 // Multiple predefined keys
    uniqueId?: string;               // Legacy unique identifier
    videoData?: VideoData;           // Single video data
    videoDataList?: VideoData[];     // Array of video data
    currentIndex?: number;           // Current video index
    
    // Player configuration
    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center' | 'custom';
    customPosition?: {
        top?: string;
        right?: string;
        bottom?: string;
        left?: string;
    };
    width?: string;
    height?: string;
    autoPlay?: boolean;
    showCloseButton?: boolean;
    showNavigation?: boolean;
    loopVideos?: boolean;
    
    // Callbacks
    onClose?: () => void;
    onNavigate?: (url: string) => void;
    onVideoChange?: (videoData: VideoData, index: number) => void;
    onError?: (error: Error) => void;
}

VideoData Interface

interface VideoData {
    video: string;                   // Video URL
    title: string;                   // Video title
    video_routing_link: string;      // Action URL
    button_text: string;            // Button text
    [key: string]: any;              // Additional properties
}

🚨 Troubleshooting

Node.js Error

If you get: ads-reels-player: This SDK requires a browser environment. DOM APIs are not available in Node.js.

Solution: This SDK is browser-only. Use it in a browser environment:

<!-- Option 1: UMD in HTML -->
<script src="https://unpkg.com/ads-reels-player@latest/dist/index.umd.js"></script>
<script>
    const player = new window.VideoPlayerSDK({ key: 'demo-1' });
    player.init();
</script>

<!-- Option 2: ES Modules in HTML -->
<script type="module">
    import { VideoPlayerSDK } from 'https://unpkg.com/ads-reels-player@latest/dist/index.es.js';
    const player = new VideoPlayerSDK({ key: 'demo-1' });
    await player.init();
</script>

Import Error

If you get: SyntaxError: The requested module 'ads-reels-player' does not provide an export named 'VideoPlayerSDK'

Solutions:

Use UMD in browser: <script src="https://unpkg.com/ads-reels-player@latest/dist/index.umd.js"></script>
Use ES modules: import { VideoPlayerSDK } from 'https://unpkg.com/ads-reels-player@latest/dist/index.es.js'
Install locally: npm install ads-reels-player and use import { VideoPlayerSDK } from 'ads-reels-player'

Video Not Loading

Check that video URLs are accessible
Use HTTPS URLs for better compatibility
Test with predefined keys first: key: 'demo-1'

Player Not Visible

In Node.js: The player won't render visually (server-side only)
In Browser: Make sure you're running in a browser environment

📦 Package Contents

dist/index.umd.js - UMD module for browser usage
dist/index.es.js - ES module for modern browsers
dist/index.d.ts - TypeScript declarations
README.md - This documentation

🎯 Quick Reference

Minimal Working Example

<script src="https://unpkg.com/ads-reels-player@latest/dist/index.umd.js"></script>
<script>
    const player = new window.VideoPlayerSDK({ key: 'demo-1' });
    player.init();
</script>

Minimal Working Example (ES Modules)

<script type="module">
    import { VideoPlayerSDK } from 'https://unpkg.com/ads-reels-player@latest/dist/index.es.js';
    const player = new VideoPlayerSDK({ key: 'demo-1' });
    await player.init();
</script>

📚 Additional Resources

Setup Guide - Complete setup instructions
Usage Guide - Detailed usage examples
Browser Demo - Interactive demo
Simple Demo - Basic usage example

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions, please open an issue on GitHub.

Your video player is now ready to use! 🎉

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ads-reels-player

🚀 Quick Start

Installation

⚠️ Important: Browser-Only SDK

Basic Usage (Vanilla JavaScript)

ES Modules (Modern Browsers)

Node.js/ES Modules

📋 Available Predefined Keys

🎯 Usage Examples

Example 1: Predefined Key (Easiest)

Example 2: Custom Video Data

Example 3: Multiple Videos with Navigation

Example 4: With Callbacks

🎨 Positioning Options

🎮 Player Controls

🌐 Framework Support

React

Vue

Angular

⚠️ Important Notes

Browser-Only SDK

Environment Detection

React Dependencies

Supported Environments

🔧 API Reference

VideoPlayerSDK Constructor

Configuration Options

VideoData Interface

🚨 Troubleshooting

Node.js Error

Import Error

Video Not Loading

Player Not Visible

📦 Package Contents

🎯 Quick Reference

Minimal Working Example

Minimal Working Example (ES Modules)

📚 Additional Resources

📄 License

🤝 Contributing

📞 Support