@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"
},
})
`

$3

#### 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=',
],
onLoadSuccess: () => { / ... / },
})
`

Lưu ý:
- Thay 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