npm package: @osiris-smarttv/util-native
Description: Util detect platform SmartTV
Latest version: 3.1.0

# @osiris-smarttv/util-native

Thư viện tiện ích native cho ứng dụng SmartTV (LG webOS, Samsung Tizen, Hisense VIDAA, trình duyệt).

Đã cập nhật để build và chạy ổn định trên Node 20 với Rollup 4 và TypeScript 5.

## Yêu cầu
- Node >= 20
- Yarn 1.x hoặc npm

## Cài đặt
```bash
yarn add @osiris-smarttv/util-native
# hoặc
npm i @osiris-smarttv/util-native
```

## Tính năng chính
- Phát hiện nền tảng dựa trên `@react4tv/smart-tv-platform`
- Bộ API lấy thông tin thiết bị, mạng, màn hình, thoát/restart app
- Xuất bản ESM và CJS + type declarations

## Sử dụng cơ bản
```ts
import NativeUtil, { PlatformInstance, PlatformName, EnumPlatform } from '@osiris-smarttv/util-native'

// Khởi tạo (tùy chọn scripts native theo nền tảng)
NativeUtil.init({
  scripts: [],
  onLoadSuccess: () => {
    const deviceName = NativeUtil.getDeviceName()
    const net = NativeUtil.getInternetInfo()
    console.log(deviceName, net)
  },
})

// Thông tin thiết bị
NativeUtil.getDeviceId()
NativeUtil.getAppName()
NativeUtil.getAppVersion()
NativeUtil.getManufacturer()
NativeUtil.getBrandName()
NativeUtil.getModelName()
NativeUtil.getOSVersion()
NativeUtil.getTVScreenSize() // { width, height }
NativeUtil.getInternetInfo() // { state, type, ipAddress, ... }

// Phát hiện nền tảng
const name = NativeUtil.getPlatformName() // 'tizen' | 'web0s' | 'browser' | ...
PlatformInstance.isTizen()
PlatformInstance.isWebOS()
PlatformInstance.isHisense()
PlatformInstance.isSmartTV()

// Điều khiển vòng đời
NativeUtil.exit()
NativeUtil.restartApp()
```

## Test trên Browser với fakePlatform
Khi develop/test trên browser (không phải SmartTV thật), bạn có thể giả lập platform **KHÔNG CẦN** import script native:

```ts
import NativeUtil, { EnumPlatform } from '@osiris-smarttv/util-native'

// Test Tizen platform trên browser - KHÔNG CẦN script Tizen
NativeUtil.init({
  fakePlatform: EnumPlatform.TIZEN,
  // scripts: [], // Không cần truyền scripts
  onLoadSuccess: () => {
    console.log('Testing Tizen platform behavior')
    // Sẽ nhận được data MẶC ĐỊNH của Tizen
    console.log(NativeUtil.getDeviceName()) 
    // => "Tizen-UA43RU7400KXXV-Test:5.0"
    
    console.log(NativeUtil.getDeviceId())
    // => "BfDqb532upKjLe/OrisDxdf3=Test"
    
    console.log(NativeUtil.getManufacturer())
    // => "Samsung Electronics"
    
    console.log(NativeUtil.getInternetInfo())
    // => { state: 'connected', type: 'Unidentified' }
  },
})

// Test WebOS platform - KHÔNG CẦN script WebOS
NativeUtil.init({
  fakePlatform: EnumPlatform.WEB_OS,
  onLoadSuccess: () => {
    console.log('Testing WebOS platform behavior')
    // Sẽ nhận được data MẶC ĐỊNH của WebOS
    console.log(NativeUtil.getDeviceName())
    // => "WebOS-LG69UA-Test:5.0"
    
    console.log(NativeUtil.getDeviceId())
    // => "d4636-483489h-3879872873d1Test"
    
    console.log(NativeUtil.getManufacturer())
    // => "LG Electronics"
  },
})
```

### Data mặc định khi dùng fakePlatform

#### Tizen (EnumPlatform.TIZEN)
```ts
{
  deviceInfo: {
    appId: "tizen.app.test",
    version: "5.0.0",
    deviceName: "Tizen-UA43RU7400KXXV-Test:5.0",
    uid: "BfDqb532upKjLe/OrisDxdf3=Test",
    appName: "App Tizen Test",
    appVersion: "1.0.0",
    brandName: "Samsung",
    manufacturer: "Samsung Electronics",
    modelName: "UA43RU7400KXXV"
  },
  screen: { width: window.innerWidth, height: window.innerHeight },
  connectionStatus: { state: 'connected', type: 'Unidentified' }
}
```

#### WebOS (EnumPlatform.WEB_OS)
```ts
{
  deviceInfo: {
    appId: "webos.app.test",
    version: "5.0.0",
    deviceName: "WebOS-LG69UA-Test:5.0",
    uid: "d4636-483489h-3879872873d1Test",
    appName: "App WebOS Test",
    appVersion: "1.0.0",
    brandName: "LG",
    manufacturer: "LG Electronics",
    modelName: "LG69UA"
  },
  screen: { width: window.innerWidth, height: window.innerHeight },
  connectionStatus: { state: 'connected', type: 'Unidentified' }
}
```

**Lưu ý quan trọng:**
- ✅ `fakePlatform` chỉ hoạt động khi detect ra **browser** (không phải SmartTV thật)
- ✅ **KHÔNG CẦN** import script native của platform đang giả lập
- ✅ Data trả về là **giá trị mặc định** để test logic, không phải data thật
- ❌ Trên SmartTV thật, `fakePlatform` sẽ bị **BỎ QUA** và dùng platform thực tế

## Tích hợp Hisense (VIDAA)
Thư viện có sẵn lớp `HisensePlatform` và sẽ tự kích hoạt nếu phát hiện thiết bị Hisense.

- Cần tải script VIDAA trước khi sử dụng API Hisense:
```ts
NativeUtil.init({
  scripts: [
    'https://tvmodules-vidaa.vidaahub.com/deviceapi/vidaatv.js?from=<client_id issued for partner>',
  ],
  onLoadSuccess: () => { /* ... */ },
})
```

Lưu ý:
- Thay `<client_id issued for partner>` bằng client_id do VIDAA cung cấp.
- Một số API Hisense có thể khác nhau theo model/firmware; thư viện có cơ chế dự phòng và sử dụng WebRTC để dò IP LAN khi cần.

## Xuất bản/Build cục bộ
```bash
yarn build       # tạo lib/esm và lib/cjs
yarn watch       # build ở chế độ watch
```

## Ví dụ (example app)
Thư mục `example/` chứa ứng dụng React demo. Chạy:
```bash
cd example
yarn
yarn start
```

## API xuất ra
- Mặc định: `export default` là `NativeUtil`
- Kiểu dữ liệu: `DeviceInfoT`, `BaseInfoT`, `ConnectionT`, `ScreenT`
- Hằng/sự kiện: `ListenerEvent`, `NetworkStatus`, `NetworkType`, `EventList`
- Tiện ích nền tảng: `PlatformInstance`, `PlatformName`

## Góp ý & Vấn đề
Vui lòng mở issue tại repo để báo lỗi/đề xuất.

## License
MIT