webOS API

The webOS API provides methods for retrieving TV-specific information and settings.

Methods of this API is compatible with methods of the webOS.js library used on the previous versions of webOS TV. If you have used methods of webOS.js to implement your app, we recommend that you replace the webOS.js library with the webOSTV.js library.

Note

Some methods of webOS.js are not executed on webOS TV. In the webOSTV.js library, only the methods supported by TV are provided.

Methods

Type	Name	Description
Member	libVersion	Holds properties representing the build version of the webOSTV.js library.
Member	platform	Holds properties representing the platform identification of webOS variants.
Method	deviceInfo	Returns the device-specific information.
	fetchAppId	Returns the app ID of the caller app.
	fetchAppInfo	Returns the appinfo.json data of the caller app with a cache saved to webOS.appInfo.
	fetchAppRootPath	Returns the full URI path of the caller app.
	platformBack	Emulates the back key of the remote controller to move backward 1 level.
	systemInfo	Returns the system-specific information.
	keyboard.isShowing	Checks whether the virtual keyboard is visible.
	service.request	Creates and sends a service request to the system of the webOS TV.

libVersion

Description

A member representing the build version of the webOSTV.js library.

Properties

None

Example

if (Number(webOS.libVersion.split('.')[0]) > 0) {
  // use webOSDev APIs
}

See also

None

platform

Description

A member representing the platform identification of webOS variants.

Properties

Name	Type	Description
tv	Boolean	Indicate whether the platform identification is webOS TV. If the platform identification is not webOS TV, undefined is returned. true: webOS TV

Example

if (webOS.platform.tv === true) {
    // calls TV specific service APIs
} else {
    console.log('This device is not TV.');
}

See also

None

deviceInfo

Description

Returns the device-specific information regarding the TV model, OS version, SDK version, screen size, and resolution.

Parameters

Name Type Description Required

devicecallback(info)

Function

The function to call once the information is collected.

info: JSON object containing the device information details
Properties

Name	Type	Description	Required
modelName	String	The model name of the device in UTF-8 format.	Required
version	String	The full name of TV SW version. You can check the value in the software version of the TV Settings menu.	Required
versionMajor	Number	The subset of TV SW version: Major version number.	Required
versionMinor	Number	The subset of TV SW version: Minor version number.	Required
versionDot	Number	The subset of TV SW version: Revision version number.	Required
sdkVersion	String	The webOS TV SDK version in X.X.X format. You can check the value in the webOS TV version of the TV Settings menu. For more detail of SDK version, see webOS TV SDK Introduction.	required
screenWidth	Number	The screen width in pixels for video playback. For the app resolution (width) for graphics display, use `window.innerWidth`.	Required
screenHeight	Number	The screen height in pixels for video playback. For the app resolution (height) for graphics display, use `window.innerHeight`.	Required
uhd	Boolean	Indicates whether the device supports Ultra HD resolution. true: The device supports Ultra HD resolution. false: The device does not support Ultra HD resolution.	Required
uhd8K	Boolean	Indicates whether the device supports 8K UHD resolution. true: The device supports 8K UHD resolution. false: The device does not support 8K UHD resolution.	Required
oled	Boolean	Indicates whether the display type of device is OLED or not. true: The display type is OLED. false: The display type is LCD.	Optional*
ddrSize	String	The size of DDR DRAM in Bytes. For example, if the size of DDR DRAM is 3G, the return value is '3G'.	Optional*
hdr10	Boolean	Indicate whether the device supports HDR10. true: The device supports HDR10. false: The device does not support HDR10.	Required
dolbyVision	Boolean	Indicate whether the device supports Dolby Vision. true: The device supports Dolby Vision. false: The device does not support Dolby Vision.	Required
dolbyAtmos	Boolean	Indicate whether the device supports Dolby Atmos. From webOSTV.js v1.2.6, it returns whether the device supports Dolby Atmos considering the connection status of external ARC devices and sound settings. true: The device supports Dolby Atmos. false: The device does not support Dolby Atmos.	Required
brandName	String	The brand name of the device. ex) "LG"	Required
manufacturer	String	The manufacturer of the device. ex) "LG Electronics"	Required
mainboardMaker	String	The mainboard maker of the device. ex) "LG"	Optional*
platformBizType	String	The platform business type of the device. "LG" "wee": The platform business type is not "LG".	Required
tuner	Boolean	Indicates whether the device supports tuner or not. true: The device supports tuner. false: The device is tunerless.	Required
* On the previous version of webOS TV that does not support this property, return undefined.

Yes

Call returns

Returns undefined.

Example

webOS.deviceInfo(function (device) {
  if (device.modelName.indexOf('32LB') > -1) {
    // do something
  }

  var version = device.version.split('.');
  if (Number(version[0]) > 3 || Number(device.versionMajor) > 3) {
    // do something
    if (Number(version[1]) > 2 || Number(device.versionMinor) > 2) {
      // do something
      if (Number(version[2]) > 13 || Number(device.versionDot) > 13) {
        // do something
      }
    }
  }

  var sdkVersion = device.sdkVersion.split('.');
  if (sdkVersion[0] === '3') {
    // do something
  }

  if (device.screenWidth === 1920 && device.screenHeight === 1080) {
    // do something
  }

  if (device.uhd && device.uhd === true) {
    // shows UHD contents
  }

  if (device.uhd8K && device.uhd8K === true) {
    // shows 8K UHD contents
  }

  if (device.oled && device.oled === true) {
    // do something
  }

  if (device.ddrSize) {
    var ddrSize = device.ddrSize.split('G')[0];
    // do something
  }

  if (device.hdr10 && device.hdr10 === true) {
    // play HDR10 contents
  }

  if (device.dolbyVision && device.dolbyVision === true) {
    // play Dolby Vision contents
  }

  if (device.dolbyAtmos && device.dolbyAtmos === true) {
    // play Dolby ATMOS contents
  }

  if (device.brandName && device.brandName === "LG") {
    // Do something
  }

  if (device.manufacturer && device.manufacturer === "LG Electronics") {
    // Do something
  }

  if (device.mainboardMaker && device.mainboardMaker === "LG") {
    // Do something
  }

  if (device.platformBizType && device.platformBizType === "LG") {
    // Do something
  }

  if (device.tuner === false) {
    // The device is tunerless
  }
  
});

See also

systemInfo

fetchAppId

Description

Returns an app ID of an app calling this method.

Parameters

None

Call returns

Name	Type	Description
appId	String	The app ID

Example

var appId = webOS.fetchAppId();
if (appId.length !== 0) {
  webOS.service.request('com.webos.service.drm', {
    method: 'load',
    parameters: {
      appId: appId,
      drmType: 'playready',
    },
    onSuccess: function (res) {
      // sendDrmMessage
    },
    onFailure: function (res) {
      // error handling
    },
  });
} else {
  console.error('Getting application ID failed.');
}

See also

fetchAppInfo

fetchAppInfo

Description

Returns the appinfo.json data of the caller app with a saved cache.

Parameters

Name

Type

Description

Required

appinfocallback

Function

The function to be called upon completion

Name	Type	Description
info	object	The JSON object read from the app's appinfo.json file. If it is not found, undefined is returned.

path

String

An optional relative file path to read appinfo.json. The file name (appinfo.json) must be included in the file path.

If your app is packaged into an IPK file, get the path using fetchAppRootPath method.
If your app is hosted by a server, the path will be the URL of the server.

Call returns

Returns undefined.

Example

var path = webOS.fetchAppRootPath();
if (path.length !== 0) {
  // It works only in the case of packaged application
  webOS.fetchAppInfo(function (info) {
    if (info) {
      var version = info.version && info.version.split('.');
      if (Number(version[0]) > 1) {
        // different implementation
      }
    } else {
      console.error('Error occurs while getting appinfo.json.');
    }
  }, path + 'appinfo.json');
} else {
  console.error('Getting application root path failed.');
}

See also

fetchAppId
fetchAppRootPath

fetchAppRootPath

Description

Returns the full URI path of the caller app.

Parameters

None

Call returns

Name	Type	Description
uri	String	The app's URI path where the app is located

Example

var path = webOS.fetchAppRootPath();
if (path.length !== 0) {
  // It works only in the case of packaged application
  webOS.fetchAppInfo(function (info) {
    if (info) {
      var version = info.version && info.version.split('.');
      if (Number(version[0]) > 1) {
        // different implementation
      }
    } else {
      console.error('Error occurs while getting appinfo.json.');
    }
  }, path + 'appinfo.json');
} else {
  console.error('Getting application root path failed.');
}

See also

None

platformBack

Description

Emulates the back key of the remote controller to move backward 1 level. On webOS TV 6.0 or higher, a popup asking whether to exit the app is displayed, and on webOS TV 5.0 or lower, the Home launcher is launched. For more information, see Back Button .

Parameters

None

Call returns

None

Example

function initPage() {
  document.querySelector('#refresh').addEventListener('click', function () {
    window.location.reload();
  });
  ...
  document
    .querySelector('#platformBack')
    .addEventListener('click', function () {
      webOS.platformBack();
    });
}

See also

None

systemInfo

Description

Returns the system-specific information regarding country, service country, and timezone.

Parameters

None

Call returns

Name	Type	Description
country	String	The country that TV broadcasts. If the value does not exist, undefined is returned.
smartServiceCountry	String	The country where the Smart service is provided. If the value does not exist, undefined is returned.
timezone	String	The time zone that TV broadcasts. If the value does not exist, undefined is returned.

Example

var sysInfo = webOS.systemInfo;
if (
  (sysInfo.country && sysInfo.country === 'KOR') ||
  (sysInfo.smartServiceCountry && sysInfo.smartServiceCountry === 'KOR') ||
  (sysInfo.timezone && sysInfo.timezone)
) {
  // shows Korean contents
}

See also

deviceInfo

keyboard.isShowing

Description

Checks whether the virtual keyboard is visible.
On the previous version of webOS TV that does not support this property, undefined is returned.

Parameters

None

Call returns

Name	Type	Description
show	Boolean	Indicates whether the virtual keyboard is displayed or hidden. true: the virtual keyboard is displayed. false: the virtual keyboard is hidden.

Example

if (webOS.keyboard.isShowing() === true) {
  // other div style fade out
} else {
  console.log('Keyboard is hidden or this API is not supported.');
}

See also

None

service.request

Description

Creates and sends a service request to the system of the webOS TV.

Parameters

Name

Type

Description

Required

uri

String

The service URI.
It accepts the normal service URI format, as well as the extended format with the service method included.

Yes

param

Object

Service request options.
Properties

Name	Type	Description	Required
method	String	The service method being called.	No
parameters	Object	The JSON object of the request parameters to send.	No
subscribe	Boolean	Indicates whether a subscription is desired for this request. true: Request the subscription. false: Not request the subscription.	No
resubscribe	Boolean	Indicates whether the request should resubscribe after a failure has occurred. true: Request the re-subscription. false: Not request the re-subscription.	No
onSuccess	Function	The callback function called when the method succeeds.	No
onFailure	Function	The callback function called when the method fails.	No
onComplete	Function	The callback function called when a request is complete (regardless of success or failure).	No

Call returns

Name

Type

Description

requestObject

Object

Resulting request object. This object can be used to cancel subscriptions.
Properties

Name	Type	Description
uri	String	The full-service request URI, including method name.
params	Object	The JSON object of the request parameters to send.
subscribe	Boolean	Indicates whether a subscription is desired for this request. true: subscribed false: not subscribed
resubscribe	Boolean	Indicates whether the request should resubscribe after a failure has occurred. true: resubscribed false: not resubscribed
onSuccess	Function	The callback function called when the method succeeds.
onFailure	Function	The callback function called when the method fails.
onComplete	Function	The callback function called when a request is complete (regardless of success or failure).
send	function	Sends the request. It is automatically called on creation. No argument is required.
cancel	function	Cancels the service request and any associated subscription. No argument is required.

Complete Callback Returns

Name	Type	Description
response	Object	The JSON object containing the service's response data; either one of proper response data or error details.

Success Callback Returns

Name	Type	Description
response	Object	The JSON object containing the service's response data

Failure Callback Returns

Name	Type	Description
error	Object	The JSON object containing the service's error details.

Example

function callSystemService() {
  webOS.service.request('luna://com.palm.systemservice', {
    method: 'time/getSystemTime',
    parameters: { subscribe: true },
    onSuccess: function (res) {
      console.log('system time suc', res);
    },
    onFailure: function (res) {
      console.log('system time fail', res);
    },
  });
}

See also

None

No Headings

webOS News

LG Electronics Announces Call for Participants for the LG webOS Hackathon 2024

LG Smart TVs Unlock Limitless Entertainment and Personal Growth With New Apps

webOS API

libVersion

platform

deviceInfo

fetchAppId

fetchAppInfo

fetchAppRootPath

platformBack

systemInfo

keyboard.isShowing

service.request