Add APL Support to Your Skill Code

// Use the RequestHelper class
import com.amazon.ask.request.RequestHelper;
// (other imports here)

public class HelloWorldIntentHandler implements RequestHandler {

    @Override
    public boolean canHandle(HandlerInput input) {
        // logic to determine when to use this handler
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {
        // ...other code used with all devices

        // Check for APL support on the user's device
        if (RequestHelper.forHandlerInput(input)
                .getSupportedInterfaces()
                .getAlexaPresentationAPL() != null) {

            // Code to send APL directives can go here
        }
    }
}

package handlers;

import static com.amazon.ask.request.Predicates.intentName;
import static util.Constants.HELLO_WORLD_TOKEN; // String "helloworldToken"

import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.exception.AskSdkException;
import com.amazon.ask.model.Response;
import com.amazon.ask.model.interfaces.alexa.presentation.apl.RenderDocumentDirective;
import com.amazon.ask.request.RequestHelper;
import com.amazon.ask.response.ResponseBuilder;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;

public class HelloWorldIntentHandler implements RequestHandler {

    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("HelloWorldIntent"));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {
        String speechText = "Hello world.";
        ResponseBuilder responseBuilder = input.getResponseBuilder();

        if (RequestHelper.forHandlerInput(input)
                .getSupportedInterfaces()
                .getAlexaPresentationAPL() != null) {
            try {
                // Retrieve the JSON document and put into a string/object map
                ObjectMapper mapper = new ObjectMapper();
                TypeReference<HashMap<String, Object>> documentMapType = 
                    new TypeReference<HashMap<String, Object>>() {};

                Map<String, Object> document = mapper.readValue(
                    new File("helloworldDocument.json"), 
                    documentMapType);

                // Use builder methods in the SDK to create the directive.
                RenderDocumentDirective renderDocumentDirective = RenderDocumentDirective.builder()
                        .withToken(HELLO_WORLD_TOKEN)
                        .withDocument(document)
                        .build();

                // Add the directive to a responseBuilder. 
                responseBuilder.addDirective(renderDocumentDirective);

                // Tailor the speech for a device with a screen.
                speechText += " You should now also see my greeting on the screen.";

            } catch (IOException e) {
                throw new AskSdkException("Unable to read or deserialize the hello world document", e);
            }
        } else {
            // Change the speech output since the device does not have a screen.
            speechText += " This example would be more interesting on a device with a screen, such as an Echo Show or Fire TV.";
        }

        // add the speech to the response and return it.

        return responseBuilder
            .withSpeech(speechText)
            .withSimpleCard("Hello World with APL", speechText)
            .build();
    }

}

package handlers;

import static com.amazon.ask.request.Predicates.intentName;
import static util.Constants.HELLO_WORLD_WITH_BUTTON_TOKEN; // String "helloworldWithButtonToken"

import java.io.File;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.exception.AskSdkException;
import com.amazon.ask.model.Response;
import com.amazon.ask.model.interfaces.alexa.presentation.apl.RenderDocumentDirective;
import com.amazon.ask.request.RequestHelper;
import com.amazon.ask.response.ResponseBuilder;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;

public class HelloWorldWithButtonIntentHandler implements RequestHandler {

    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("HelloWorldWithButtonIntent"));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {
        String speechText = "Hello world.";
        ResponseBuilder responseBuilder = input.getResponseBuilder();

        if (RequestHelper.forHandlerInput(input)
                .getSupportedInterfaces()
                .getAlexaPresentationAPL() != null) {
            try {
                // The JSON file containing the Hello World APL 
                // document is in the "resources" folder. Retrieve it
                //  and add it to the directive.
                ObjectMapper mapper = new ObjectMapper();
                TypeReference<HashMap<String, Object>> documentMapType = new TypeReference<HashMap<String, Object>>() {
                };
                Map<String, Object> document = mapper.readValue(new File("helloworldWithButtonDocument.json"), documentMapType);

                // Build the directive. 
                RenderDocumentDirective renderDocumentDirective = RenderDocumentDirective.builder()
                    .withToken(HELLO_WORLD_WITH_BUTTON_TOKEN)
                    .withDocument(document)
                    .build();
                
                responseBuilder.addDirective(renderDocumentDirective);
                            
                // update speech to mention the screen
                speechText += " Welcome to Alexa Presentation Language. Click the button to see what happens!";

            } catch (IOException e) {
                throw new AskSdkException("Unable to read or deserialize the hello world document", e);
            }

        } else {
            speechText += " This example would be more interesting on a device with a screen, such as an Echo Show or Fire TV.";
        }

        return responseBuilder
            .withSpeech(speechText)
            .withSimpleCard("Hello World with APL", speechText)
            .build();
    }
}

package handlers;

import java.util.Map;
import java.util.Optional;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.impl.UserEventHandler;
import com.amazon.ask.model.Response;
import com.amazon.ask.model.interfaces.alexa.presentation.apl.UserEvent;

public class HelloWorldButtonEventHandler implements UserEventHandler {

    @Override
    public boolean canHandle(HandlerInput input, UserEvent userEvent) {      
        // This is a typed handler, so it only runs for UserEvents.
        // Since an APL skill might have multiple buttons that generate UserEvents,
        // use the event source ID to determine the button press that triggered
        // this event and use the correct handler. In this example, the string
        // 'fadeHelloTextButton' is the ID we set on the AlexaButton in the document.

        // The userEvent.getSource() method returns an Object. Cast as a Map so we
        // can retrieve the id.
        Map<String,Object> eventSourceObject = (Map<String,Object>) userEvent.getSource();
        String eventSourceId = (String) eventSourceObject.get("id");
        return eventSourceId.equals("fadeHelloTextButton");
    }

    @Override
    public Optional<Response> handle(HandlerInput input, UserEvent userEvent) {

        String speechText = "Thank you for clicking the button! I imagine you already noticed that the text faded away. Tell me to start over to bring it back!";
        
        return input.getResponseBuilder()
            .withSpeech(speechText)
            .withReprompt("Tell me to start over if you want me to bring the text back into view. Or, you can just say hello again.")
            .build();
    }
    
}

package handlers;

import static com.amazon.ask.request.Predicates.intentName;
import static util.Constants.HELLO_WORLD_WITH_BUTTON_TOKEN; // String "helloworldWithButtonToken"

import java.util.Optional;

import com.amazon.ask.dispatcher.request.handler.HandlerInput;
import com.amazon.ask.dispatcher.request.handler.RequestHandler;
import com.amazon.ask.model.Response;
import com.amazon.ask.model.interfaces.alexa.presentation.apl.AnimateItemCommand;
import com.amazon.ask.model.interfaces.alexa.presentation.apl.AnimatedOpacityProperty;
import com.amazon.ask.model.interfaces.alexa.presentation.apl.ExecuteCommandsDirective;
import com.amazon.ask.request.RequestHelper;
import com.amazon.ask.response.ResponseBuilder;
import com.fasterxml.jackson.databind.JsonNode;

public class StartOverIntentHandler implements RequestHandler {
    @Override
    public boolean canHandle(HandlerInput input) {
        return input.matches(intentName("AMAZON.StartOverIntent"));
    }

    @Override
    public Optional<Response> handle(HandlerInput input) {
        String speechText;
        ResponseBuilder responseBuilder = input.getResponseBuilder();        
        
        if (RequestHelper.forHandlerInput(input)
            .getSupportedInterfaces()
            .getAlexaPresentationAPL() != null) {
            // Get the APL visual context information from the JSON request
            // and check that the document identified by the 
            // HELLO_WORLD_WITH_BUTTON_TOKEN token ("helloworldWithButtonToken")
            // is currently displayed.
            JsonNode context = input.getRequestEnvelopeJson().get("context");
            if (context.has("Alexa.Presentation.APL") && 
                (context.get("Alexa.Presentation.APL")
                    .get("token")
                    .asText()
                    .equals(HELLO_WORLD_WITH_BUTTON_TOKEN))){

                speechText = "OK, I'm going to try to bring that text back into view.";

                AnimatedOpacityProperty animatedOpacityProperty = AnimatedOpacityProperty.builder()
                    .withTo(1.0)
                    .build();
    
                AnimateItemCommand animateItemCommand = AnimateItemCommand.builder()
                    .withComponentId("helloTextComponent")
                    .withDuration(3000)
                    .addValueItem(animatedOpacityProperty)
                    .build();

                    // Note that the token for ExecuteCommands must 
                    // match the token provided in the RenderDocument
                    // directive that originally displayed the document
                    ExecuteCommandsDirective executeCommandsDirective = ExecuteCommandsDirective.builder()
                        .withToken(HELLO_WORLD_WITH_BUTTON_TOKEN)
                        .addCommandsItem(animateItemCommand)
                        .build();
                
                    responseBuilder.addDirective(executeCommandsDirective);
            } else {
                // Device is NOT displaying the expected document, so provide
                // relevant output speech.
                speechText = "Hmm, there isn't anything for me to reset. Try invoking the 'hello world with button intent', then click the button and see what happens!";
            }
            
        } else {
            speechText = "Hello, this sample is more interesting when used on a device with a screen. Try it on an Echo Show, Echo Spot or a Fire TV device.";
        }
     
        return responseBuilder
                .withSpeech(speechText)
                .build();
    }
}