APLClient 1
The APLClient
interface exposes directives and events to enable communication between a native Alexa Presentation Language (APL) client and an inter-process communication (IPC) APL view host. Additionally the interface enables the IPC client to invoke local rendering of APL payloads initiated by the APL client.
Header
{
"namespace": "APLClient",
"version": 1
}
Directives
Inbound messages from the Alexa client about APL document rendering.
createRenderer
Instructs the IPC client to create an APL IPC renderer instance with the APL view host’s create
API. The action completes rendering of the associated APL document.
After the APL document is created, the APL IPC renderer and native renderer communicate through viewhostEvent
and sendMessageToViewhost
.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "createRenderer" }, "payload": { "windowId": "{{STRING}}", "token": "{{STRING}}" } }
Payload parameters
Parameter | Description | Type |
---|---|---|
windowId |
Identifies which window to render the specified APL document. | string |
token |
Unique identifier for the APL document. | string |
sendMessageToViewhost
Instructs the IPC client to send the message from APL Core to the IPC view host through the onMessage
API.
The IPC client uses windowId
to identify the view host instance to target with the message payload.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "sendMessageToViewhost" }, "payload": { "windowId": "{{STRING}}", "payload": "{{APL CORE OBJECT}}" } }
Payload parameters
Parameter | Description | Type |
---|---|---|
windowId |
Identifies the APL window or document instance for which the APL Core message is intended. | string |
payload |
Opaque serialized APL Core Library message payload to be provided to the IPC APL view host. | object |
Events
Outbound messages from the IPC client about APL document rendering.
initializeRenderersRequest
Send this event from the IPC client to initialize any native APLClientRenderer
instances required for the IPC client’s windows.
When an APL document is received targeting one of the windows, the Alexa client responds with a createRenderer
directive.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "initializeRenderersRequest" }, "payload": { "rendererInstances": [ { "windowId": "{{STRING}}", "supportedExtensions": [ "{{STRING}}" ] } ] } }
Payload parameters
Parameter | Description | Type |
---|---|---|
rendererInstances |
Array of APL renderer instances to initialize. | array |
rendererInstances.windowId |
windowId for the APL renderer instance to initialize. |
string |
rendererInstances.supportedExtensions |
Array of APL extension URIs for the extensions to be supported by this renderer instance. | array of strings |
metricsReport
Send this event from the APL IPC view host to report APL metrics defined in the view host.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "metricsReport" }, "payload": { "type": "{{STRING}}", "windowId": "{{STRING}}", "payload": "{{APL METRIC OBJECT}}" } }
Payload parameters
Parameter | Description | Type |
---|---|---|
type |
Type of APL metric, which is defined by the APL view host. | string |
windowId |
Identifies the APL renderer/window instance from which this metric event emanates. | string |
payload |
Opaque serialized APL view host message payload to be passed to the native APL client. | object |
viewhostEvent
This event is sent from the APL IPC view host for communicating with APL Core.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "viewhostEvent" }, "payload": { "windowId": "{{STRING}}", "payload": "{{APL VIEWHOST OBJECT}}" } }
Payload parameters
Parameter | Description | Type |
---|---|---|
windowId |
Identifies the APL renderer or window instance from which this view host event emanates. | string |
payload |
Opaque serialized APL view host message payload to be passed to the native APL client. | object |
renderCompleted
Send a renderCompleted
event from the IPC client when the IPC APL view host has completed inflation of an APL document after receipt of a createRenderer
directive.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "renderCompleted" }, "payload": { "windowId": "{{STRING}}" } }
Payload parameters
Parameter | Description | Type |
---|---|---|
windowId |
Identifies the APL window where the document has completed rendering. | string |
renderDocumentRequest
Send this event from the IPC client to initiate the local rendering of an APL document.
This is similar to the Alexa client receiving an AVS APL RenderDocument
directive.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "renderDocumentRequest" }, "payload": { "windowId": "{{STRING}}", "token": "{{STRING}}", "payload": { "document": {{OBJECT}}, "datasources": {{OBJECT}}, "supportedViewports": {{ARRAY OF SUPPORTED VIEWPORTS}} } } }
Payload parameters
Parameter | Description | Type |
---|---|---|
windowId |
Identifies which window to render the specified APL document. | string |
token |
Unique identifier for the document. | string |
payload |
Wrapper on APL document payload. | object |
payload.document |
APL document to be rendered. | object |
payload.datasources |
Data sources to bind to the rendered document. | object |
payload.supportedViewports |
Array of viewport specifications that the specified APL document supports. For more details about viewport support, see Select the Viewport Profiles Your Document Supports. |
array |
executeCommandsRequest
Send this event from the IPC client to initiate APL commands on a document rendered with the renderDocumentRequest
.
This is similar to the Alexa client receiving an AVS APL ExecuteCommands directive.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "executeCommandsRequest" }, "payload": { "token": "{{STRING}}", "payload": { "commands": {{ARRAY OF APL COMMANDS}} } } }
Payload parameters
Parameter | Description | Type |
---|---|---|
token |
Unique identifier for the document. | string |
payload |
Wrapper on APL commands payload. | object |
payload.commands |
Array of APL commands to run on the local APL document identified by the token. | array |
clearDocumentRequest
Send this event from the IPC client to clear a local APL document rendered through the renderDocumentRequest
and release the native renderer.
Example message
{ "header": { "version": 1 "namespace": "APLClient", "name": "clearDocumentRequest" }, "payload": { "windowId": "{{STRING}}", "token": "{{STRING}}" } }
Payload parameters
Parameter | Description | Type |
---|---|---|
windowId |
Identifies the window to clear for the local APL document. | string |
token |
Identifier for the local APL document to clear. | string |
Related topics
Last updated: Apr 11, 2022