APL Support for Item Selection

When a customer views a screen of your APL skill, they may want to select particular items in different ways.

For example, a customer might say "Select the second one". You can support this behavior by using the built-in AMAZON.SelectIntent in your interaction model in combination with the Sequence component in your APL document.

A customer might also say "Select this" or "Select that". AMAZON.SelectIntent provides anaphora-based selection if you fill out the Anaphor slot.

Ordinal-based selection

When an APL Sequence component is used by a skill that also has AMAZON.SelectIntent in its interaction model, a customer can say "Select the third one" to send an AMAZON.SelectIntent request to the skill. When this happens, in addition to the selected ordinal (3) in the ListPosition slot, AMAZON.SelectIntent will also provide the APL component identifier (id) of the list item that is at the third position in the Sequence component, provided the third item is visible on-screen. Thus, the selection behavior may differ across devices of different sizes.

These are the relevant AMAZON.SelectIntent properties for ordinal selection.

Property Type Description
ListPosition Object
(slot)		 The slot that will be populated inside AMAZON.SelectIntent when a customer tries to select an item by ordinal.
ListPosition.value String The position to which the customer refers. For example, for the utterance “select the second one”, ListPosition.value will contain the value "2".
ListPosition.resolutions.resolutionsPerAuthority Collection The set of resolutions available for the ListPosition slot value. For APL, the only items of interest are those whose authority is set to amz1.er-authority.visual-context. For more information, see resolutionsPerAuthority object.

Anaphora-Based selection

The built-in AMAZON.SelectIntent also provides anaphora-based selection. When a customer says "Select this" or "Select that", the skill receives an AMAZON.SelectIntent with the Anaphor slot filled out. If an APL document is on-screen when AMAZON.SelectIntent is invoked, the resolutions.resolutionsPerAuthority collection under the Anaphor slot will have the APL component identifier (id) of the top-level APL component in the current document. The top-level component is the component that is at the root of the visual hierarchy. This is useful when a customer is looking at a detail view of an item and wants to select that item based on what they see.

Here are the relevant AMAZON.SelectIntent properties:

Property Type Description
Anaphor Object
(slot)		 This is the slot that will be populated inside AMAZON.SelectIntent when a customer tries to select an item by anaphor.
Anaphor.value String The anaphor value, such as “this” or “that”, that the customer used.
ListPosition.resolutions.resolutionsPerAuthority Collection The set of resolutions available for the Anaphor slot value. For these purposes, the resolutions of interest are those whose authority is set to amz1.er-authority.visual-context.

ListPosition.resolutions.resolutionsPerAuthority

For both ordinal and anaphor-based selection, the items in the ListPosition.resolutions.resolutionsPerAuthority collection whose authority values are set to amz1.er -authority.visual-context have the following relevant properties.

Property Type Description
authority String Set to amz1.er-authority.visual-context
status Object Object containing the status of the resolution
status.code String Status code set to ER_SUCCESS_MATCH when the ListPosition is successfully resolved. Set to ER_SUCCESS_NO_MATCH when resolution fails.
values Array An array of resolved values for the ListPosition slot.
values.value Object An object representing a resolved value for the ListPosition slot.
values.value.id String The id of the APL component that is in the ordinal position identified by ListPosition.value.

ListPosition slot resolution for ordinal selection

Here is an example of an AMAZON.SelectIntent with a resolved ListPosition slot for position number 3. The status code ER_SUCCESS_MATCH indicates that the identifier was successfully resolved.

{
    "version": "1.0",
    "session": {
            //Session information	
    },
    "context": {
        "Alexa.Presentation.APL": {
            "token": "anydocument",
            "version": "AriaRenderer-1.0.209.0",
            "componentsVisibleOnScreen": [{
                //APL Context
            }]
        },
        "System": {
            //System information
        },
        "Viewport": {
            //Viewport information
        }
    },
    "request": {
        "type": "IntentRequest",
        "requestId": "[RequestId]",
        "timestamp": "2018-10-22T03:53:47Z",
        "locale": "en-US",
        "intent": {
            "name": "AMAZON.SelectIntent",
            "confirmationStatus": "NONE",
            "slots": {
                "ListPosition": {
                    "name": "ListPosition",
                    "value": "3",
                    "resolutions": {
                        "resolutionsPerAuthority": [{
                            "authority": "amz1.er-authority.visual-context",
                            "status": {
                                "code": "ER_SUCCESS_MATCH"
                            },
                            "values": [{
                                "value": {
                                    "id": "blue"
                                }
                            }]
                        }]
                    },
                    "confirmationStatus": "NONE",
                    "source": "USER"
                },
                "Anaphor": {
                    "name": "Anaphor",
                    "confirmationStatus": "NONE"
                },
                "VisualModeTrigger": {
                    "name": "VisualModeTrigger",
                    "confirmationStatus": "NONE"
                },
                "PositionRelation": {
                    "name": "PositionRelation",
                    "confirmationStatus": "NONE"
                }
            }
        }
    }
}

ListPosition slot resolution for anaphor-based selection

Here is an example of an AMAZON.SelectIntent with an APL identifier resolved inside the Anaphor slot for a value of this.

{
    "version": "1.0",
    "session": {
        //Session information
    },
    "context": {
        "Alexa.Presentation.APL": {
            "token": "anydocument",
            "version": "AriaRenderer-1.0.209.0",
            "componentsVisibleOnScreen": [{
                //APL Context
            }]
        },
        "System": {
            //System information
        },
        "Viewport": {
            //Viewport information
        }
    },
    "request": {
        "type": "IntentRequest",
        "requestId": "[RequestId]",
        "timestamp": "2018-10-22T06:14:55Z",
        "locale": "en-US",
        "intent": {
            "name": "AMAZON.SelectIntent",
            "confirmationStatus": "NONE",
            "slots": {
                "ListPosition": {
                    "name": "ListPosition",
                    "confirmationStatus": "NONE"
                },
                "Anaphor": {
                    "name": "Anaphor",
                    "value": "this",
                    "resolutions": {
                        "resolutionsPerAuthority": [{
                            "authority": "amz1.er-authority.visual-context",
                            "status": {
                                "code": "ER_SUCCESS_MATCH"
                            },
                            "values": [{
                                "value": {
                                    "id": "bluecheesedetail"
                                }
                            }]
                        }]
                    },
                    "confirmationStatus": "NONE",
                    "source": "USER"
                },
                "VisualModeTrigger": {
                    "name": "VisualModeTrigger",
                    "confirmationStatus": "NONE"
                },
                "PositionRelation": {
                    "name": "PositionRelation",
                    "confirmationStatus": "NONE"
                }
            }
        }
    }
}
Was this page helpful?

Last updated: Nov 28, 2023