npm package: @react4tv/smart-tv-platform
Description: Util detect platform SmartTV
Author: Nguyễn Sỹ Thành Công
Latest version: 1.1.1

# 📺 Smart TV Platform Detection

[![npm version](https://img.shields.io/npm/v/@react4tv/smart-tv-platform.svg)](https://www.npmjs.com/package/@react4tv/smart-tv-platform)
[![npm downloads](https://img.shields.io/npm/dm/@react4tv/smart-tv-platform.svg)](https://www.npmjs.com/package/@react4tv/smart-tv-platform)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)

A powerful TypeScript library for detecting Smart TV platforms and devices. Perfect for building cross-platform Smart TV applications that need to adapt to different TV operating systems.

## ✨ Features

- 🎯 **Accurate Detection**: Detects major Smart TV platforms including Tizen, WebOS, Hisense VIDAA, and more
- 🔧 **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- 📱 **Multi-Platform**: Supports Samsung, LG, Hisense, Sony, Toshiba, and other Smart TV brands
- 🚀 **Lightweight**: Minimal bundle size with zero dependencies
- 🛡️ **Reliable**: Battle-tested detection algorithms for production use
- 📦 **Tree-shakable**: ES modules and CommonJS support

## 🎮 Supported Platforms

| Platform | Brand | Detection Method |
|----------|-------|------------------|
| **Tizen** | Samsung Smart TV | User Agent + SMART-TV |
| **WebOS** | LG Smart TV | Web0S, WebOS, LG Browser |
| **Hisense VIDAA** | Hisense Smart TV | VIDAA, Odin, Model detection |
| **Sony** | Sony Smart TV | Sony, BRAVIA, CEBrowser |
| **Toshiba** | Toshiba Smart TV | Toshiba, TSBNetTV |
| **Android TV** | Various brands | Android TV, AFTSS |
| **Fire TV** | Amazon | AFTSS, AFTS |
| **Roku** | Roku devices | Roku, DVP |
| **Apple TV** | Apple | AppleTV, TV OS |

## 📦 Installation

### npm
```bash
npm install @react4tv/smart-tv-platform
```

### yarn
```bash
yarn add @react4tv/smart-tv-platform
```

### pnpm
```bash
pnpm add @react4tv/smart-tv-platform
```

## 🚀 Quick Start

### Basic Usage

```typescript
import { PlatformInstance, PlatformName } from '@react4tv/smart-tv-platform';

// Check if running on Smart TV
if (PlatformInstance.isSmartTV()) {
  console.log('Running on Smart TV!');
  
  // Detect specific platform
  if (PlatformInstance.isTizen()) {
    console.log('Samsung Tizen TV detected');
  } else if (PlatformInstance.isWebOS()) {
    console.log('LG WebOS TV detected');
  } else if (PlatformInstance.isHisense()) {
    console.log('Hisense VIDAA TV detected');
  }
}

// Get platform name
const platform = PlatformInstance.getPlatformName();
console.log('Current platform:', platform); // 'tizen', 'webOS', 'hisense', etc.
```

### Advanced Detection

```typescript
import { DeviceUtil } from '@react4tv/smart-tv-platform';

// Browser detection
if (DeviceUtil.isChrome()) {
  console.log('Chrome browser detected');
}

if (DeviceUtil.isAppleSafari()) {
  console.log('Safari browser detected');
}

// Hisense specific detection
if (DeviceUtil.isHisense()) {
  console.log('Hisense TV detected');
  
  if (DeviceUtil.isHisenseVIDAA()) {
    const version = DeviceUtil.getVIDAAVersion();
    console.log('VIDAA version:', version);
  }
  
  const browserEngine = DeviceUtil.getHisenseBrowserEngine();
  console.log('Browser engine:', browserEngine); // 'Odin', 'Opera', 'Chrome'
  
  const modelGen = DeviceUtil.getHisenseModelGeneration();
  console.log('Model generation:', modelGen); // 'MT565x', 'MSD6586', etc.
}

// Tizen version detection
if (DeviceUtil.isTizenVersion(5)) {
  console.log('Tizen 5.x detected');
}
```

## 📚 API Reference

### Platform Class

The main class for platform detection.

#### Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `isTizen()` | `boolean` | Check if running on Samsung Tizen |
| `isWebOS()` | `boolean` | Check if running on LG WebOS |
| `isHisense()` | `boolean` | Check if running on Hisense VIDAA |
| `isSmartTV()` | `boolean` | Check if running on any Smart TV |
| `isApple()` | `boolean` | Check if running on Apple device |
| `isChrome()` | `boolean` | Check if running on Chrome browser |
| `getPlatformName()` | `PlatformName` | Get current platform name |

### DeviceUtil Object

Utility functions for detailed device detection.

#### Smart TV Detection

| Method | Return Type | Description |
|--------|-------------|-------------|
| `isTizen()` | `boolean` | Samsung Tizen detection |
| `isTizenVersion(version)` | `boolean` | Tizen version detection |
| `isWebOS()` | `boolean` | LG WebOS detection |
| `isHisense()` | `boolean` | Hisense TV detection |
| `isHisenseVIDAA()` | `boolean` | Hisense VIDAA detection |
| `isHisenseSmartTV()` | `boolean` | Hisense Smart TV detection |
| `isSamsungTV()` | `boolean` | Samsung TV detection |
| `isAndroidTV()` | `boolean` | Android TV detection |
| `isFireTV()` | `boolean` | Amazon Fire TV detection |
| `isRoku()` | `boolean` | Roku device detection |
| `isAppleTV()` | `boolean` | Apple TV detection |
| `isSony()` | `boolean` | Sony TV detection |
| `isToshiba()` | `boolean` | Toshiba TV detection |
| `isSmartTV()` | `boolean` | Any Smart TV detection |

#### Hisense Specific

| Method | Return Type | Description |
|--------|-------------|-------------|
| `getVIDAAVersion()` | `number \| null` | Get VIDAA OS version |
| `isHisenseMT()` | `boolean` | Hisense MT chipset detection |
| `isHisenseMSD()` | `boolean` | Hisense MSD chipset detection |
| `isHisenseNT()` | `boolean` | Hisense NT chipset detection |
| `isHisenseOdin()` | `boolean` | Hisense Odin browser detection |
| `getHisenseBrowserEngine()` | `string` | Get browser engine (Odin/Opera/Chrome) |
| `getHisenseModelGeneration()` | `string \| null` | Get model generation |

#### Browser Detection

| Method | Return Type | Description |
|--------|-------------|-------------|
| `isChrome()` | `boolean` | Chrome browser detection |
| `isAppleSafari()` | `boolean` | Safari browser detection |
| `isEdge()` | `boolean` | Edge browser detection |
| `isIE()` | `boolean` | Internet Explorer detection |

#### Device Type Detection

| Method | Return Type | Description |
|--------|-------------|-------------|
| `isMobile()` | `boolean` | Mobile device detection |
| `isTablet()` | `boolean` | Tablet device detection |

### PlatformName Enum

```typescript
enum PlatformName {
  Tizen = "tizen",
  WebOS = "webOS",
  Sony = "sony",
  Panasonic = "panasonic",
  Apple = "apple",
  TiVo = "tivo",
  Toshiba = "toshiba",
  Browser = "browser",
  iOS = "ios",
  Android = "android",
  Hisense = "hisense"
}
```

## 🎯 Use Cases

### React Smart TV App

```typescript
import React, { useEffect, useState } from 'react';
import { PlatformInstance, DeviceUtil } from '@react4tv/smart-tv-platform';

const SmartTVApp: React.FC = () => {
  const [platform, setPlatform] = useState<string>('');

  useEffect(() => {
    if (PlatformInstance.isSmartTV()) {
      setPlatform(PlatformInstance.getPlatformName());
      
      // Platform-specific optimizations
      if (PlatformInstance.isTizen()) {
        // Samsung Tizen specific code
        console.log('Optimizing for Samsung Tizen');
      } else if (PlatformInstance.isWebOS()) {
        // LG WebOS specific code
        console.log('Optimizing for LG WebOS');
      } else if (PlatformInstance.isHisense()) {
        // Hisense specific code
        console.log('Optimizing for Hisense VIDAA');
      }
    }
  }, []);

  return (
    <div>
      <h1>Smart TV App</h1>
      <p>Platform: {platform}</p>
    </div>
  );
};
```

### Conditional Loading

```typescript
import { DeviceUtil } from '@react4tv/smart-tv-platform';

// Load platform-specific modules
const loadPlatformModule = async () => {
  if (DeviceUtil.isTizen()) {
    return import('./tizen-module');
  } else if (DeviceUtil.isWebOS()) {
    return import('./webos-module');
  } else if (DeviceUtil.isHisense()) {
    return import('./hisense-module');
  }
  return import('./default-module');
};
```

### Analytics and Tracking

```typescript
import { PlatformInstance, DeviceUtil } from '@react4tv/smart-tv-platform';

const trackPlatformUsage = () => {
  const platform = PlatformInstance.getPlatformName();
  const isSmartTV = PlatformInstance.isSmartTV();
  
  // Send analytics
  analytics.track('platform_detected', {
    platform,
    isSmartTV,
    browserEngine: DeviceUtil.isHisense() ? DeviceUtil.getHisenseBrowserEngine() : 'unknown'
  });
};
```

## 🔧 Configuration

### TypeScript Configuration

Add to your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "lib": ["dom", "es2020"],
    "moduleResolution": "node"
  }
}
```

### Build Configuration

The library supports both ES modules and CommonJS:

```typescript
// ES modules (recommended)
import { PlatformInstance } from '@react4tv/smart-tv-platform';

// CommonJS
const { PlatformInstance } = require('@react4tv/smart-tv-platform');
```

## 🧪 Testing

```typescript
import { PlatformInstance, DeviceUtil } from '@react4tv/smart-tv-platform';

// Mock user agent for testing
Object.defineProperty(window.navigator, 'userAgent', {
  value: 'Mozilla/5.0 (SMART-TV; Linux; Tizen 5.0) AppleWebKit/537.36',
  configurable: true
});

// Test platform detection
console.log(PlatformInstance.isTizen()); // true
console.log(PlatformInstance.isSmartTV()); // true
```

## 📈 Performance

- **Bundle Size**: ~2KB gzipped
- **Detection Speed**: < 1ms
- **Memory Usage**: Minimal
- **Tree Shaking**: Fully supported

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/react-4-smart-tv/smart-tv-platform.git

# Install dependencies
yarn install

# Build the library
yarn build

# Run tests
yarn test

# Watch mode
yarn watch
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Thanks to all Smart TV manufacturers for their platforms
- Community contributors and testers
- TypeScript team for excellent tooling

## 📞 Support

- 📧 Email: [thanhcongns94@gmail.com](mailto:thanhcongns94@gmail.com)
- 🐛 Issues: [GitHub Issues](https://github.com/react-4-smart-tv/smart-tv-platform/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/react-4-smart-tv/smart-tv-platform/discussions)

---

<div align="center">
  <strong>Built with ❤️ for the Smart TV community</strong>
</div>