APL¶

Outgoing Messages¶

DataSourceUpdate¶

Notifies the platform implementation of a dynamic data source update.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "DataSourceUpdate"
        }
    },
    "payload": {
        "type": {{String}},
        "payload": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description
type	String	Yes	The type of data source update received.
payload	String	Yes	The data source update payload in JSON format.
token	String	Yes	The presentation token associated with the APL document.

InterruptCommandSequence¶

Notifies the platform implementation to clear the APL document rendering.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "InterruptCommandSequence"
        }
    },
    "payload": {
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
token	String	Yes	The presentation token associated with the APL document.

UpdateAPLRuntimeProperties¶

Notifies the platform implementation of APL runtime properties to be used during rendering.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "UpdateAPLRuntimeProperties"
        }
    },
    "payload": {
        "properties": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
properties	String	Yes	String in JSON format containing updated APL runtime properties.

RenderDocument¶

Notifies the platform implementation that an APL document needs rendering.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "RenderDocument"
        }
    },
    "payload": {
        "payload": {{String}},
        "token": {{String}},
        "windowId": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description
payload	String	Yes	The APL document to be rendered represented as a JSON string.
token	String	Yes	The presentation token associated with the APL document.
windowId	String	Yes	The window ID where the APL document will be rendered or empty string for default window.

ExecuteCommands¶

Notifies the platform implementation that an APL document needs rendering.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "ExecuteCommands"
        }
    },
    "payload": {
        "payload": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
payload	String	Yes	The APL commands to be executed represented as a JSON string.
token	String	Yes	The presentation token associated with the APL document.

ClearDocument¶

Notifies the platform implementation to clear the APL document rendering.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "ClearDocument"
        }
    },
    "payload": {
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
token	String	Yes	The presentation token associated with the APL document.

Incoming Messages¶

ProcessActivityEvent¶

Notifies the Engine of an activity event.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "ProcessActivityEvent"
        }
    },
    "payload": {
        "source": {{String}},
        "event": {{ActivityEvent}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
source	String	Yes	The source value for the activity event.
event	ActivityEvent	Yes	The activity event type.

SetAPLMaxVersion¶

Notifies the Engine of the maximum APL version supported.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SetAPLMaxVersion"
        }
    },
    "payload": {
        "version": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
version	String	Yes	The maximum APL version supported.

SendUserEvent¶

Notifies the Engine that user generated an event.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SendUserEvent"
        }
    },
    "payload": {
        "payload": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
payload	String	Yes	The APL user event represented as a JSON string.

SendDataSourceFetchRequestEvent¶

Notifies the Engine of a data source fetch request.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SendDataSourceFetchRequestEvent"
        }
    },
    "payload": {
        "type": {{String}},
        "payload": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
type	String	Yes	The type of data source fetch request.
payload	String	Yes	The APL user event represented as a JSON string.

SendDeviceWindowState¶

Notifies the Engine of the current window state.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SendDeviceWindowState"
        }
    },
    "payload": {
        "state": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
state	String	Yes	JSON string representing the payload of the window state https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/display-window.html#windowstate-context-object.

SendDocumentState¶

Notifies the Engine that APL runtime generated visual document state.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SendDocumentState"
        }
    },
    "payload": {
        "state": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
state	String	Yes	JSON string representing the payload of the rendered document state https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/presentation-apl.html#rendereddocumentstate.

SendRuntimeErrorEvent¶

Notifies the Engine that an APL runtime error occurred.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SendRuntimeErrorEvent"
        }
    },
    "payload": {
        "payload": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
payload	String	Yes	The APL runtime error event represented as a JSON string.

ClearAllExecuteCommands¶

Notifies the Engine that APL render finished clearing all commands.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "ClearAllExecuteCommands"
        }
    }
}

SetPlatformProperty¶

Notifies the Engine of properties such as vehicle driving state, day/night mode, and custom theme id.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SetPlatformProperty"
        }
    },
    "payload": {
        "name": {{String}},
        "value": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
name	String	Yes	The name of the property to be set.
value	String	Yes	The value that the property will be set to.

ExecuteCommandsResult¶

Notifies the Engine of the command execution result.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "ExecuteCommandsResult"
        }
    },
    "payload": {
        "token": {{String}},
        "result": {{Bool}},
        "error": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description
token	String	Yes	The token associated with the commands.
result	Bool	Yes	True if rendering was successful, otherwise false.
error	String	Yes	Error message if rendering failed, otherwise empty.

SetDocumentIdleTimeout¶

Notifies the Engine of the idle timeout value.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "SetDocumentIdleTimeout"
        }
    },
    "payload": {
        "timeout": {{int64}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
timeout	int64	Yes	Idle timeout value in milliseconds.

RenderDocumentResult¶

Notifies the Engine of command execution result.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "RenderDocumentResult"
        }
    },
    "payload": {
        "token": {{String}},
        "result": {{Bool}},
        "error": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description
token	String	Yes	The token associated with the APL document.
result	Bool	Yes	True if rendering was successful, otherwise false.
error	String	Yes	Error message if rendering failed, otherwise empty.

ClearCard¶

Notifies the Engine that APL render finished clearing document.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "APL",
            "action": "ClearCard"
        }
    }
}

Enums¶

ActivityEvent¶

Values¶

Value	Description
"ACTIVATED"	GUI switched to active state.
"DEACTIVATED"	GUI become inactive.
"ONE_TIME"	GUI processed one-time event (touch/scroll/etc).
"INTERRUPT"	Interrupt event (touch).
"UNKNOWN"	Guard option for unknown received state.