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.

{
    "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