Public Member Functions
virtual void	renderDocument (const std::string &jsonPayload, const std::string &token, const std::string &windowId)=0

virtual void	clearDocument (const std::string &token)=0

virtual void	executeCommands (const std::string &jsonPayload, const std::string &token)=0

virtual void	interruptCommandSequence (const std::string &token)=0

virtual void	dataSourceUpdate (const std::string &sourceType, const std::string &jsonPayload, const std::string &token)=0

virtual void	updateAPLRuntimeProperties (const std::string &properties)=0

void	clearCard ()

void	clearAllExecuteCommands ()

void	sendUserEvent (const std::string &payload)

void	sendDataSourceFetchRequestEvent (const std::string &type, const std::string &payload)

void	sendRuntimeErrorEvent (const std::string &payload)

void	setAPLMaxVersion (const std::string &aplMaxVersion)

void	setDocumentIdleTimeout (std::chrono::milliseconds documentIdleTimeout)

void	renderDocumentResult (const std::string &token, const bool result, const std::string &error)

void	executeCommandsResult (const std::string &token, const bool result, const std::string &error)

void	processActivityEvent (const std::string &source, const ActivityEvent event)

void	sendDocumentState (const std::string &state)

void	sendDeviceWindowState (const std::string &state)

void	setPlatformProperty (const std::string &name, const std::string &value)

Detailed Description

APL should be extended to handle receiving Alexa Presentation RenderDocument and ExecuteCommands directives from AVS. These directives contain metadata for rendering or operating on display cards for devices with GUI support. For more information about Alexa Presentation Language (APL) see the interface overview:

https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/understand-apl.html

Deprecated:: This platform interface is deprecated. Use the Alexa Auto Services Bridge (AASB) message broker to publish and subscribe to AASB messages instead.

See also: aace::core::MessageBroker

Member Function Documentation

◆ renderDocument()

virtual void aace::apl::APL::renderDocument	(	const std::string &	jsonPayload,
		const std::string &	token,
		const std::string &	windowId
	)

pure virtual

Notifies the platform implementation that a RenderDocument directive has been received. Once called, the client should render the document based on the APL specification in the payload in structured JSON format.

Note: The payload may contain customer sensitive information and should be used with utmost care. Failure to do so may result in exposing or mishandling of customer data.

Parameters

[in]	jsonPayload	The payload of the Alexa.Presentation.APL.RenderDocument directive which follows the APL specification.
[in]	token	The APL presentation token associated with the document in the payload.
[in]	windowId	The target windowId.

◆ clearDocument()

virtual void aace::apl::APL::clearDocument ( const std::string & token )

pure virtual

Notifies the platform implementation when the client should clear the APL display card. Once the card is cleared, the platform implementation should call clearCard().

Parameters

[in] token The APL presentation token associated with the current rendered document.

◆ executeCommands()

virtual void aace::apl::APL::executeCommands	(	const std::string &	jsonPayload,
		const std::string &	token
	)

pure virtual

Notifies the platform implementation that an ExecuteCommands directive has been received.

Parameters

[in]	jsonPayload	The payload of the Alexa.Presentation.APL.ExecuteCommands directive in structured JSON format.
[in]	token	The APL presentation token associated with the current rendered document.

◆ interruptCommandSequence()

virtual void aace::apl::APL::interruptCommandSequence ( const std::string & token )

pure virtual

Notifies the platform implementation that a command execution sequence should be interrupted.

Parameters

[in] token The APL presentation token associated with the current rendered document.

◆ dataSourceUpdate()

virtual void aace::apl::APL::dataSourceUpdate	(	const std::string &	sourceType,
		const std::string &	jsonPayload,
		const std::string &	token
	)

pure virtual

Notifies the platform implementation of a dynamic data source update. Please refer to APL documentation for more information:

https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/apl-data-source.html

Parameters

[in]	sourceType	DataSource type.
[in]	jsonPayload	The payload of the directive in structured JSON format.
[in]	token	The APL presentation token associated with the current rendered document.

◆ updateAPLRuntimeProperties()

virtual void aace::apl::APL::updateAPLRuntimeProperties ( const std::string & properties )

pure virtual

Notifies the platform implementation of APL runtime environment properties that must be updated. The Engine will generate these values based on the setAPLProperty() values. The APL runtime will be affected by these values.

Parameters

[in]

properties

A JSON object in string form containing the APL runtime properties that need to be updated.

{
     "<property name>" : "<property value>"
}

Attention: Supported names and values.

Name	Value	Description
drivingState	parked, moving	Sets the Automobile driving state runtime property.
theme	light, dark, light-<themeId>, dark-<themeId>	APL viewport theme value.
video	enabled, disabled	Indicates if video should be allowed in the APL document.

◆ clearCard()

void aace::apl::APL::clearCard ( )

Notifies the Engine to clear the card from the screen and release any focus being held.

◆ clearAllExecuteCommands()

void aace::apl::APL::clearAllExecuteCommands ( )

Notifies the Engine to clear all pending ExecuteCommands directives and mark them as failed.

◆ sendUserEvent()

void aace::apl::APL::sendUserEvent ( const std::string & payload )

Notifies the Engine to send UserEvent event to AVS.

https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/apl-interface.html#userevent-request

Parameters

[in] payload The UserEvent event payload. The caller of this function is responsible to pass the payload as it defined by AVS.

◆ sendDataSourceFetchRequestEvent()

void aace::apl::APL::sendDataSourceFetchRequestEvent	(	const std::string &	type,
		const std::string &	payload
	)

Notifies the Engine to send a LoadIndexListData event to AVS.

https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/apl-interface.html#loadindexlistdata-request https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/apl-data-source.html

Parameters

type	The type of data source fetch request. The only supported value is "dynamicIndexList".
payload	The `DataSourceFetchRequest` event payload. The caller of this function is responsible to pass the payload as defined by AVS.

◆ sendRuntimeErrorEvent()

void aace::apl::APL::sendRuntimeErrorEvent ( const std::string & payload )

Notifies the Engine to send an APL RuntimeError event to AVS

https://developer.amazon.com/en-US/docs/alexa/alexa-presentation-language/apl-interface.html#runtimeerror-request

Parameters

payload The RuntimeError event payload. The caller of this function is responsible to pass the payload as defined by AVS.

◆ setAPLMaxVersion()

void aace::apl::APL::setAPLMaxVersion ( const std::string & aplMaxVersion )

Set the APL version supported by the runtime component.

Parameters

[in] aplMaxVersion The APL version supported.

◆ setDocumentIdleTimeout()

void aace::apl::APL::setDocumentIdleTimeout ( std::chrono::milliseconds documentIdleTimeout )

Set a custom document idle timeout. When the idle timeout is reached, the Engine will call clearDocument().

Parameters

[in] documentIdleTimeout The timeout in milliseconds.

Note: Will be reset for every directive received from AVS.

◆ renderDocumentResult()

void aace::apl::APL::renderDocumentResult	(	const std::string &	token,
		const bool	result,
		const std::string &	error
	)

Notifies the Engine with the result of a renderDocument notification.

Parameters

[in]	token	The APL presentation token associated with the current rendered document.
[in]	result	Rendering result (true on executed, false on exception).
[in]	error	Error message provided in case result is false.

◆ executeCommandsResult()

void aace::apl::APL::executeCommandsResult	(	const std::string &	token,
		const bool	result,
		const std::string &	error
	)

Notifies the Engine with the result of an executeCommands notification.

Parameters

[in]	token	The APL presentation token associated with the current rendered document.
[in]	result	Rendering result (true on executed, false on exception).
[in]	error	Error message provided in case result is false.

◆ processActivityEvent()

void aace::apl::APL::processActivityEvent	(	const std::string &	source,
		const ActivityEvent	event
	)

Notifies the Engine of an activity change event. The APL runtime can report whether the rendered document is active or inactive. If active, the idle timer is stopped and prevents clearDocument. If inactive, the idle timer is started and clearDocument will be called after timer expiration.

Parameters

[in]	source	The source of the activity event.
[in]	event	The activity change event.

◆ sendDocumentState()

void aace::apl::APL::sendDocumentState ( const std::string & state )

Notifies the Engine of rendered document state. The format of the state is a JSON string representing the payload object of the RenderedDocumentState sent with APL events.

https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/presentation-apl.html#rendereddocumentstate

Parameters

[in] state The visual state of the rendered components.

◆ sendDeviceWindowState()

void aace::apl::APL::sendDeviceWindowState ( const std::string & state )

Notifies the Engine of the current window state. The format of the state is a JSON string representing the payload object of the WindowState context sent for the Alexa.Display.Window interface.

https://developer.amazon.com/en-US/docs/alexa/alexa-voice-service/display-window.html#windowstate-context-object

Parameters

[in] state The window state context object.

◆ setPlatformProperty()

void aace::apl::APL::setPlatformProperty	(	const std::string &	name,
		const std::string &	value
	)

The rendered APL experience will rely on the value of some defined properties. The platform implementation must report these values to provide a safe visual experience in the vehicle.

Parameters

[in]	name	The name of the property.
[in]	value	The value of the property.

Note: Contact your Solutions Architect for an updated list of automotive themes identifiers.

Attention: Supported names and values.

Name	Value	Description
drivingState	parked, moving	Set this property when vehicle driving state changes.
uiMode	day, night	This affects the contrast of certified APL experiences.
themeId	(night) black, gray, (day) gray1, gray2	Optional value that can be empty string. Valid values for day and night mode are specified.

Public Member Functions

Detailed Description

Member Function Documentation

◆ renderDocument()

◆ clearDocument()

◆ executeCommands()

◆ interruptCommandSequence()

◆ dataSourceUpdate()

◆ updateAPLRuntimeProperties()

◆ clearCard()

◆ clearAllExecuteCommands()

◆ sendUserEvent()

◆ sendDataSourceFetchRequestEvent()

◆ sendRuntimeErrorEvent()

◆ setAPLMaxVersion()

◆ setDocumentIdleTimeout()

◆ renderDocumentResult()

◆ executeCommandsResult()

◆ processActivityEvent()

◆ sendDocumentState()

◆ sendDeviceWindowState()

◆ setPlatformProperty()