Settings Service

Service URI - luna://com.webos.settingsservice

Provides a method for retrieving system setting value.

Methods

Method

Description

Supported in Emulator

getSystemSettings

Retrieves values from system settings with keys.

Yes

getSystemSettings

Description

Retrieves values from system settings with keys that are specified in an array as a parameter. The following keys are available:

Category

Key Name

Description

Type

-

localeInfo

Locale settings for language, keyboard, time zone, and clock.

Object

option

country

Country code (ISO 3166-1 alpha-3).

String

option

smartServiceCountryCode2

Service country code (ISO 3166 alpha-2). This code is related to LG Apps service.

String

option

audioGuidance

Indicates whether to enable the audio guidance for the accessibility menu or not. This key is available on webOS TV 3.0 or higher.

String

caption

captionEnable

Indicates whether to enable the closed caption setting for the accessibility menu or not.

String

caption

captionAnalog

Get the EIA608 Standard CAPTION service. Possible values are: "cc1"/"cc2"/"cc3"/"cc4"/"t1"/"t2"/"t3"/"t4"

String

caption

captionDigital

Get the EIA708 Standard CAPTION service. Possible values are: "off"/"svc1"/"svc2"/"svc3"/"svc4"/"svc5"/"svc6"

String

caption

captionStyle

Get the style of the closed caption to a broadcast style or to a user setting style. Possible values are: "auto"/"manual"

String

caption

captionSize

Get the size of the closed caption. Possible values are: "small"/"standard"/"large"

String

caption

captionFont

Get the font of the closed caption. Possible values are: "font0"/"font1"/"font2"/"font3"/"font4"/"font5"/"font6"/"font7"

String

caption

captionTextColor

Get the text color of the closed caption. Possible values are: "white"/"black"/"red"/"green"/"blue"/"cyan"/"magenta"/"yellow"

String

caption

captionTextOpacity

Get the text transparency of the closed caption. Possible values are: "flash"/"translucent"/"transparent"/"solid"

String

caption

captionBgColor

Get the background color of the closed caption. Possible values are: "white"/"black"/"red"/"green"/"blue"/"cyan"/"magenta"/"yellow"

String

caption

captionBgOpacity

Get the background transparency of the closed caption. Possible values are: "flash"/"translucent"/"transparent"/"solid"

String

caption

captionEdgeType

Get the border style of the closed caption. Possible values are: "none"/"uniform"/"raised"/"depressed"/"left_drop_shadow"/"right_drop_shadow"

String

caption

captionEdgeColor

Get the border color of the closed caption. Possible values are: "white"/"black"/"red"/"green"/"blue"/"cyan"/"magenta"/"yellow"

String

caption

captionWindowColor

Get the window color of the closed caption. Possible values are: "white"/"black"/"red"/"green"/"blue"/"cyan"/"magenta"/"yellow"

String

caption

captionWindowOpacity

Get the windows transparency of the closed caption. Possible values are: "translucent"/"transparent"/"solid"

String

Parameters

Name

Required

Type

Description

category

Optional

String

Category of settings.

 • If the specified keys (key) has a category, you must specify this property.

keys

Optional

String array

Keys for retrieving setting values. One of the keys and key property should be specified.

key

Optional

String

A key for retrieving the setting value. One of the keys and key property should be specified.

subscribe

Optional

Boolean

The flag that decides whether to subscribe or not. If you enable the subscription, you get an event when the value of the specified settings is changed.

 • true: Subscribe.

 • false: Do not subscribe. Call the method only once. (Default)

Remarks

The following table shows the use cases of getSystemSettings.

Case

category

keys

key

Description

Specify non-categorized key

-

-

"localeInfo"

Returns the corresponding locale setting values.

Specify a category without key.

"option"

-

-

Returns an error.

Specify key with category name

"option"

-

"country"

Returns the country setting value.

Specify key with wrong category

"option"

-

"localeInfo"

Returns an error.

Specify keys with category name

"option"

["country", "smartServiceCountryCode2"]

-

Returns the specified setting. (country and samrtServiceCountryCode2)

Specify keys included in different categories

"option"

["localeInfo", "country"]

-

Returns an error.

Specify nothing.

-

-

-

Returns an error.

Call returns

Name

Required

Type

Description

returnValue

Required

Boolean

The flag that indicates success/failure of the request.

 • true: Success

 • false: Failure

errorCode

Optional

String

errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Codes Reference of this method for more details.

errorText

Optional

String

errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Codes Reference of this method for more details.

category

Optional

String

Category string of the result setting values. It is the same as the category parameter in the method call.

method

Required

String

Method name that clarifies which method is called in subscription messages.

settings

Required

Object

Objects that hold result setting values.

subscribed

Optional

Boolean

The flag that decides whether to subscribe or not.

 • true: Subscribe

 • false: Do not subscribe. Call the method only once. (Default)

Remarks

If you subscribe to more than one key, you will receive the result data for whole keys at the first return. After the first return, you will receive the result data for each key when the corresponding system information is changed.

Error reference

Error Text

Error Description

There is no matched result from DB.

If the requested key is undefined, API returns an error.

Subscription Returns

Name

Required

Type

Description

returnValue

Required

Boolean

The flag that indicates success/failure of the request.

 • true: Success

 • false: Failure

category

Optional

String

Category string of the result setting values. It is the same as the category parameter in the method call.

method

Required

String

Method name that is used for clarifying which method is called in subscription messages.

settings

Required

Object

Objects that hold the result setting values.

Example

// Get country information
    var request = webOS.service.request('luna://com.webos.settingsservice', {
      method: 'getSystemSettings',
      parameters: {
        category: 'option',
        keys: ['country', 'smartServiceCountryCode2'],
      },
      onSuccess: function (inResponse) {
        console.log('Result: ' + JSON.stringify(inResponse));
        // To-Do something
      },
      onFailure: function (inError) {
        console.log("Failed to get settings' value");
        console.log('[' + inError.errorCode + ']: ' + inError.errorText);
        // To-Do something
        return;
      },
    });
    
    // Get locale information with subscription
    var subscriptionHandle;
    
    subscriptionHandle = webOS.service.request('luna://com.webos.settingsservice', {
      method: 'getSystemSettings',
      parameters: {
        keys: ['localeInfo'],
        subscribe: true,
      },
      onSuccess: function (inResponse) {
        if (typeof inResponse.subscribed != 'undefined') {
          if (!inResponse.subscribed) {
            console.log("Failed to subscribe settings' value");
            return;
          }
        }
    
        console.log('Result: ' + JSON.stringify(inResponse));
        // To-Do something
      },
      onFailure: function (inError) {
        console.log("Failed to get settings' value");
        console.log('[' + inError.errorCode + ']: ' + inError.errorText);
        // To-Do something
        return;
      },
    });
    ...
    
    // Get audio guidance information
    var audioGuidanceRequest = webOS.service.request(
      'luna://com.webos.settingsservice',
      {
        method: 'getSystemSettings',
        parameters: {
          category: 'option',
          keys: ['audioGuidance'],
        },
        onSuccess: function (inResponse) {
          console.log('Result: ' + JSON.stringify(inResponse));
          // To-Do something
        },
        onFailure: function (inError) {
          console.log("Failed to get settings' value");
          console.log('[' + inError.errorCode + ']: ' + inError.errorText);
          // To-Do something
          return;
        },
      }
    );
    
    // Get caption information
    var captionRequest = webOS.service.request('luna://com.webos.settingsservice', {
      method: 'getSystemSettings',
      parameters: {
        category: 'caption',
        keys: ['captionEnable'],
      },
      onSuccess: function (inResponse) {
        console.log('Result: ' + JSON.stringify(inResponse));
        // To-Do something
      },
      onFailure: function (inError) {
        console.log("Failed to get settings' value");
        console.log('[' + inError.errorCode + ']: ' + inError.errorText);
        // To-Do something
        return;
      },
    });
    
    

// Get captionAnalog information
var captionAnalogRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionAnalog"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionDigital information
var captionDigitalRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionDigital"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionStyle information
var captionStyleRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionStyle"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionSize information
var captionSizeRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionSize"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionFont information
var captionFontRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionFont"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionTextColor information
var captionTextColorRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionTextColor"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionTextOpacity information
var captionTextOpacityRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionTextOpacity"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionBgColor information
var captionBgColorRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionBgColor"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionBgOpacity information
var captionBgOpacityRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionBgOpacity"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionEdgeType information
var captionEdgeTypeRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionEdgeType"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionEdgeColor information
var captionEdgeColorRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionEdgeColor"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionWindowColor information
var captionWindowColorRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionWindowColor"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// Get captionWindowOpacity information
var captionWindowOpacityRequest = webOS.service.request(
  "luna://com.webos.settingsservice",
  {
    method: "getSystemSettings",
    parameters: {
      category: "caption",
      keys: ["captionWindowOpacity"],
    },
    onSuccess: function (inResponse) {
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get settings' value");
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
      return;
    },
  },
);

// If you need to unsubscribe the data, use cancel() method as below
    subscriptionHandle.cancel();

Return example

// Success return - country information
{
    "category": "option",
    "method": "getSystemSettings",
    "settings": {
        "smartServiceCountryCode2": "GB",
        "country": "FRA"
    },
    "returnValue": true
}

// Success return - locale information
{
    "method": "getSystemSettings",
    "settings": {
        "localeInfo": {
            "locales": {
                "UI": "en-GB",
                "TV": "en-GB",
                "FMT": "en-GB",
                "NLP": "en-GB",
                "STT": "fr-FR",
                "AUD": "fr-FR",
                "AUD2": "en-GB"
            },
            "clock": "locale",
            "keyboards": [
                "en"
            ],
            "timezone": "
        }
    },
    "returnValue": true
}

// Success return - audio guidance information
{
    "subscribed": false,
    "category": "option",
    "method": "getSystemSettings",
    "settings": {
        "audioGuidance": "off"
    },
    "returnValue": true
}

// Success return - caption information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionEnable": "off"
    },
    "returnValue": true
}



// Success return - captionAnalog information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionAnalog": "cc1"
    },
    "returnValue": true
}

// Success return - captionDigital information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionDigital": "svc1"
    },
    "returnValue": true
}

// Success return - captionStyle information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionStyle": "auto"
    },
    "returnValue": true
}

// Success return - captionSize information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionSize": "standard"
    },
    "returnValue": true
}

// Success return - captionFont information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionFont": "font0"
    },
    "returnValue": true
}

// Success return - captionTextColor information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionTextColor": "white"
    },
    "returnValue": true
}

// Success return - captionTextOpacity information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionTextOpacity": "solid"
    },
    "returnValue": true
}

// Success return - captionBgColor information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionBgColor": "black"
    },
    "returnValue": true
}

// Success return - captionBgOpacity information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionBgOpacity": "solid"
    },
    "returnValue": true
}

// Success return - captionEdgeType information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionEdgeType": "none"
    },
    "returnValue": true
}

// Success return - captionEdgeColor information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionEdgeColor": "black"
    },
    "returnValue": true
}

// Success return - captionWindowColor information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionWindowColor": "black"
    },
    "returnValue": true
}

// Success return - captionWindowOpacity information
{
    "subscribed": false,
    "category": "caption",
    "method": "getSystemSettings",
    "settings": {
        "captionWindowOpacity": "solid"
    },
    "returnValue": true
}

// Failure return
    {
    "method": "getSystemSettings",
    "returnValue": false,
    "errorText": "There is no matched result from DB"
}

See also

None

Object

settings object

The object that holds the setting values from setting service. Locale and country settings can be contained.

{
    "localeInfo": object,
    "smartServiceCountryCode2": String,
    "country": String,
    "audioGuidance": String,
    "captionEnable": String,
    "captionAnalog": String,
    "captionDigital": String,
    "captionStyle": String,
    "captionSize": String,
    "captionFont": String,
    "captionTextColor": String,
    "captionTextOpacity": String,
    "captionBgColor": String,
    "captionBgOpacity": String,
    "captionEdgeType": String,
    "captionEdgeColor": String,
    "captionWindowColor": String,
    "captionWindowOpacity": String
}

Name

Required

Type

Description

localeInfo

Optional

Object

Object that holds locale setting values.

smartServicecountryCode2

Optional

String

Service country code (ISO 3166-1 alpha-2).

country

Optional

String

Country code (ISO 3166-1 alpha-3).

audioGuidance

Optional

String

Indicates whether the audio guidance is enabled.

 • on: The audio guidance is enabled.

 • off: The audio guidance is disabled.

captionEnable

Optional

String

Indicates whether the closed caption is enabled.

 • on: The closed caption is enabled.

 • off: The closed caption is disabled.

captionAnalog

Optional

String

EIA608 Standard CAPTION service.

 • cc1: The Primary Synchronous Service (CC1) is set.

 • cc2: The Special Non-Synchronous Channel (CC2) is set.

 • cc3: The Secondary Synchronous Service (CC3) is set.

 • cc4: The Special Non-Synchronous Channel (CC4) is set.

 • t1: Text Services(T1) is set.

 • t2: Text Services(T2) is set.

 • t3: Text Services(T3) is set.

 • t4: Text Services(T4) is set.

captionDigital

Optional

String

EIA708 Standard CAPTION service.

 • off: Caption Channel Service is not set.

 • svc1: Caption Channel Service(service1) is set.

 • svc2: Caption Channel Service(service2) is set.

 • svc3: Caption Channel Service(service3) is set.

 • svc4: Caption Channel Service(service4) is set.

 • svc5: Caption Channel Service(service5) is set.

 • svc6: Caption Channel Service(service6) is set.

captionStyle

Optional

String

Whether the style of the closed caption is set to a broadcast style or to a user setting style.

 • auto: It is set as a broadcast style.

 • manual: It is set in the user style.

captionFont

Optional

String

Font of the closed caption.

 • font0

 • font1

 • font2

 • font3

 • font4

 • font5

 • font6

 • font7

captionTextColor

Optional

String

Text color of the closed caption.

 • white

 • black

 • red

 • green

 • blue

 • cyan

 • magenta

 • yellow

captionTextOpacity

Optional

String

Text transparency of the closed caption.

 • flash: The text of the close caption blinks.

 • translucent

 • transparent

 • solid: The text of the close caption is opaque.

captionBgColor

Optional

String

Background color of the closed caption.

 • white

 • black

 • red

 • green

 • blue

 • cyan

 • magenta

 • yellow

captionBgOpacity

Optional

String

Background transparency of the closed caption.

 • flash: The background of the closed caption blinks.

 • translucent

 • transparent

 • solid: The background of the closed caption is opaque.

captionEdgeType

Optional

String

Border style of the closed caption.

 • none: The border type is not set.

 • uniform

 • raised

 • depressed

 • left_drop_shadow

 • right_drop_shadow

captionEdgeColor

Optional

String

Border color of the closed caption.

 • white

 • black

 • red

 • green

 • blue

 • cyan

 • magenta

 • yellow

captionWindowColor

Optional

String

Window color of the closed caption.

 • black

 • red

 • green

 • blue

 • cyan

 • magenta

 • yellow

captionWindowOpacity

Optional

String

Window transparency of the closed caption.

 • flash: The window of the closed caption blinks.

 • translucent

 • transparent

 • solid: The window of the closed caption is opaque.

localeInfo object

Object that holds the language, keyboard, and time settings.

{
    "locales": {
        "UI": String,
        "TV": String,
        "FMT": String,
        "NLP": String,
        "STT": String,
        "AUD": String,
        "AUD2": String
    },
    "clock": String,
    "keyboards": String array,
    "timezone": String
    }

Name

Required

Type

Description

locales

Required

Object

Object that holds locale settings. Each property use language tag such as "en_US".

locales.UI

Required

String

The general language that the UI uses in most parts of the system.

locales.TV

Required

String

Language for TV such as OSD (On Screen Display).

locales.FMT

Required

String

Locale for data formats such as date format and time format.

locales.NLP

Required

String

The Natural Language Processing language.

locales.STT

Required

String

The speech-to-text language.

locales.AUD

Required

String

Language for audio language.

locales.AUD2

Required

String

Language for secondary audio language.

clock

Required

String

Clock setting shall have three possible values:

 • "12"

 • "24"

 • "locale"

keyboards

Required

String array

Added languages for the virtual keyboard (language tag)

 • Example: ["en", "ko"]

timezone

Required

String

Time zone setting value.

No Headings