@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

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

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:

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)

{
  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)

{
  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:

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ộ

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:

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