Smart Home AppSelector Trait Schema

action.devices.traits.AppSelector - This trait is used for devices which are able to switch inputs.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
availableApplications Array <Object>

A list of applications. Each application has one or more synonyms in each supported language. The first synonym is used in the response.

Properties:

Application that users of this device can interact with.

key String

Unique key for the application which is not exposed to users in speech or response.

names Array <Object>

Name of each application and its language-specific synonyms.

Properties:

Application synonyms.

name_synonym Array <String>

User-friendly synonyms for the application name for a given language. The first synonym is used in the response.

Application name.

lang String

Language code.

Required:

  • name_synonym
  • lang

Required:

  • key
  • names

Required:

  • availableApplications
Examples

Device with YouTube app

{
  "availableApplications": [
    {
      "key": "youtube",
      "names": [
        {
          "name_synonym": [
            "youtube",
            "YouTube US"
          ],
          "lang": "en"
        },
        {
          "name_synonym": [
            "youtube",
            "YouTube DE"
          ],
          "lang": "de"
        }
      ]
    }
  ]
}
Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.TV',
        traits: [
          'action.devices.traits.AppSelector'
        ],
        name: {
          defaultNames: ['TV'],
          name: 'Living Room TV',
          nicknames: ['Big TV']
        },
        willReportState: true,
        attributes: {
          availableApplications: [
            {
              key: "youtube",
              names: [
                {
                  name_synonym: [
                    "Youtube",
                    "YouTube US"
                  ],
                  lang: "en"
                },
                {
                  name_synonym: [
                    "Youtube",
                    "YouTube DE"
                  ],
                  lang: "de"
                }
              ]
            }
          ]
        },
        deviceInfo: {
          manufacturer: 'BrandX',
          model: 'hg11',
          hwVersion: '1.2',
          swVersion: '5.4'
        },
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-appselector_sync.json")
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");

  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.TV")
            .addTrait("action.devices.traits.AppSelector")
            .setName(
                Collections.singletonList("TV"),
                "Living Room TV",
                Collections.singletonList("Big TV"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "availableApplications",
                        new JSONObject[] {
                          new JSONObject()
                              .put("key", "youtube")
                              .put(
                                  "names",
                                  new JSONObject[] {
                                    new JSONObject()
                                        .put(
                                            "name_synonym",
                                            new String[] {"Youtube", "YouTube US"})
                                        .put("lang", "en"),
                                    new JSONObject()
                                        .put(
                                            "name_synonym",
                                            new String[] {"Youtube", "YouTube DE"})
                                        .put("lang", "de")
                                  })
                        }))
            .setDeviceInfo("BrandX", "hg11", "1.2", "5.4")
            .build()
      });

  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.TV",
        "traits": [
          "action.devices.traits.AppSelector"
        ],
        "name": {
          "defaultNames": [
            "TV"
          ],
          "name": "Living Room TV",
          "nicknames": [
            "Big TV"
          ]
        },
        "willReportState": true,
        "attributes": {
          "availableApplications": [
            {
              "key": "youtube",
              "names": [
                {
                  "name_synonym": [
                    "Youtube",
                    "YouTube US"
                  ],
                  "lang": "en"
                },
                {
                  "name_synonym": [
                    "Youtube",
                    "YouTube DE"
                  ],
                  "lang": "de"
                }
              ]
            }
          ]
        },
        "deviceInfo": {
          "manufacturer": "BrandX",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        }
      }
    ]
  }
}
Validator

Device STATES

Devices with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
currentApplication String

Key value of the current application that is active in the foreground.

Required:

  • currentApplication
Examples

Device with YouTube app currently active on foreground.

{
  "currentApplication": "youtube"
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.appInstall

Parameters

Install the given application.

Parameters Type Description
newApplication String

Key of the application to install.

newApplicationName String

Name of the application to install.

Examples

Install YouTube app by key

{
  "newApplication": "youtube"
}

Install YouTube app by name

{
  "newApplicationName": "YouTube US"
}

action.devices.commands.appSearch

Parameters

Search for the given application.

Parameters Type Description
newApplication String

Key of the application to search for.

newApplicationName String

Name of the application to search for.

Examples

Search for YouTube app by key

{
  "newApplication": "youtube"
}

Search for YouTube app by name

{
  "newApplicationName": "YouTube US"
}

action.devices.commands.appSelect

Parameters

Select the given application.

Parameters Type Description
newApplication String

Key of the application to select.

newApplicationName String

Name of the application to select.

Examples

Select YouTube app by key

{
  "newApplication": "youtube"
}

Select YouTube app by name

{
  "newApplicationName": "YouTube US"
}

Sample EXECUTE Request and Response

Example: Launch the YouTube app on the living room TV.

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.appSelect",
          "params": {
            "newApplication": "youtube"
          }
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          currentApplication: 'youtube',
          online: true
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-appselector_execute_1.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("currentApplication", "youtube");
                put("online", true);
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "currentApplication": "youtube",
          "online": true
        }
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.
  • noAvailableApp: The application doesn’t exist or is not available.
  • appLaunchFailed: The application failed to launch.
  • alreadyInstalledApp: The application was already installed.