webOS

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.

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

Type

Name

Description

Member

libVersion

Holds properties representing the build version of the webOSTV.js library.

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.

 

Open


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.

Syntax

webOS.deviceInfo(devicecallback(info))

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.

    Yes

    modelNameAscii

    String

    The model name of the device in ASCII format.

    Yes

    version

    String

    The full name of OS firmware version.

    Yes

    versionMajor

    Number

    The subset of OS version: Major version number.

    Yes

    versionMinor

    Number

    The subset of OS version: Minor version number.

    Yes

    versionDot

    Number

    The subset of OS version: Revision version number.

    Yes

    sdkVersion

    String

    The webOS SDK version.

    Yes

    screenWidth

    Number

    The screen width in pixels.

    Yes

    screenHeight

    Number

    The screen Height in pixels.

    Yes

    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.

    Optional

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
    }
});

See Also


fetchAppId

Description

Returns an app ID of an app calling this method.

Syntax

webOS.fetchAppId()

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

Description

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

Syntax

webOS.fetchAppInfo(callback, path)

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.

No

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.

No

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


fetchAppRootPath

Description

Returns the full URI path of the caller app.

Syntax

webOS.fetchAppRootPath()

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.

Syntax

webOS.platformBack()

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.

Syntax

webOS.systemInfo()

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


keyboard.isShowing

Description

Checks whether the virtual keyboard is visible.

Syntax

webOS.keyboard.isShowing()

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.

Syntax

webOS.service.request(uri, param)

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

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

Navigation