OpenURL Command

OpenURL requires APL 1.1 or later. Provide an alternate experience for devices running older versions of APL.

Opens a URL. The OpenURL command, if successful, opens the specified URL in a web browser or other application on the device. You must provide a suitable URL that works on the current device.

Properties

The OpenURL command has the properties shown in the following table, in addition to the common command properties. Set the type property to OpenURL.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description
source String REQUIRED The URL to open.
onFail Array of command [ ] Command to run if the URL fails to open.

For example, to open the Amazon home page in the browser on the device:

{
  "type": "OpenURL",
  "source": "https://www.amazon.com/",
  "onFail": {
    "type": "SetValue",
    "componentId": "errorText",
    "property": "text",
    "value": "Unable to open Amazon.com (${event.source.value})"
  }
}

The OpenURL command is ignored in fast mode.

source

The source property is a URL/URI suitable for launching an application on the local device. It can also be used with the HTTP or HTTPS schema to open a web page in the local web browser.

onFail

The onFail property contains one or more commands to run if the device can't open the URL. There is no guarantee that the onFail command will run within a time limit or that it will appear to be successful to the end user; for example, a URL could open a blank or error web page. However, the APL runtime should try to report failure within three seconds. The event generated for the onFail command has the following form:

"event": {
  "source": {
    "source": "OpenURL",
    "handler": "Fail",
    "value": NUMBER    // Platform-defined numerical error
  }
}

The event.source.value field passed to the onFail command will be set to a platform-defined numerical error code. This error code is not suitable for showing to the user (despite the example provided above), but may be used to send failure information back to the cloud skill through a SendEvent command.

Verify device support for opening URLs

Not all devices support opening a URL. If the device does not support opening URLs, the command is ignored and it doesn't run the onFail commands. Check the value of the allowOpenURL in the data-binding context to determine if OpenURL is supported on the device.

Was this page helpful?

Last updated: frontmatter-missing