Nesta seção, você vai aprender a modificar o back-end com segurança para adicionar elementos visuais de APL à sua resposta. Ao final, você vai ter melhorado sua solicitação de inicialização do Cake Time com os elementos visuais de APL construídos na última seção. Além disso, você vai aprender a usar o S3 no ambiente hospedado na Alexa para hospedar seus próprios ativos e usá-los para adicionar uma imagem de fundo à sua skill.
Usaremos o código do Cake Time nesta seção. Se você não fez o Curso de Cake Time e é um desenvolvedor Alexa novato, dê uma olhada no curso e volte para este módulo depois. Se você já é um desenvolvedor de skills e já tem experiência com o básico de uma skill de node.JS, fique à vontade para pular o curso e ver as instruções de configuração rápida para obter o código e a visão geral da skill de Cake Time.
Para que um dispositivo Alexa exiba seu documento APL corretamente, você só deve responder com uma diretiva de exibição quando o dispositivo suportar a APL. Essa diretiva toma a forma do Alexa.Presentation.APL.RenderDocument. Você pode incluir uma diretiva usando o node.JS SDK e chamando handlerInput.responseBuilder.addDirective({…});
Você pode adicionar uma diretiva de exibição em todas as respostas, mas nem todos os dispositivos reagirão a isso. Para responder com segurança com o Alexa.Presentation.APL.RenderDocument, o dispositivo que está chamando deve enviar o objeto de solicitação adequado. Esta informação está contida no objeto supportedInterfaces, encontrado como context.System.device.supportedInterfaces. Por exemplo, a amostra de solicitação pode estar assim:
{
...
"context": {
"System": {
...
"device": {
"deviceId": "amzn1.ask.device.1...",
"supportedInterfaces": {
"Alexa.Presentation.APL": {
"runtime": {
"maxVersion": "1.1"
}
}
}
}
...
}
}
}
Se você está usando o SDK, é fácil verificar as interfaces suportadas.
A. No LaunchRequestHandler.handle(), antes de a resposta ser criada, inclua:
if (Alexa.getSupportedInterfaces(handlerInput.requestEnvelope)['Alexa.Presentation.APL']) {
// Create Render Directive.
}
A instrução “if” (se) vai verificar se a interface da APL é enviada no envelope de solicitação. Somente neste momento é que vamos adicionar a resposta. Agora, vamos adicionar a resposta.
B. Embaixo do comentário // Create Render Directive , adicione:
handlerInput.responseBuilder.addDirective({
type: 'Alexa.Presentation.APL.RenderDocument',
document: launchDocument,
datasources: {
text: {
type: 'object',
start: "Welcome",
middle: "to",
end: "Cake Time!"
}
}
});
Note que deixamos as informações sobre a imagem de fora. Há outros passos necessários para exibir a imagem do ambiente hospedado na Alexa, então voltaremos a isto depois. Agora vamos importar o launchDocument. Vamos começar nomeando o documento launchDocument.json, pois ele representa o documento APL para solicitações de inicialização genéricas.
C. À esquerda, selecione a pasta lambda. Clique com o botão direito e selecione Create Folder (Criar Pasta). Nomeie a pasta como documentos. Inclua um novo arquivo, chamado launchDocument.json nessa pasta.
D. Dentro desse arquivo, adicione o JSON da authoring tool (ferramenta de criação) que criamos no módulo 2 (ao final do qual está o documento JSON completo).
E. Depois, importe o seguinte no topo do seu index.js :
const launchDocument = require('./documents/launchDocument.json');
A variável launchDocument no seu código javascript representa o conteúdo do arquivo json.
F. Agora implemente o código. Lembre-se de testar!
Você teve problemas ao testar as inclusões à APL? Antes de testar as mudanças do documento, precisamos habilitar a APL na aba Build (Compilar).
A. Clique na aba Build. Você vai precisar clicar em Interfaces, no lado esquerdo.
B. Role a tela e ative a Alexa Presentation Language. Note que o bloco se expandiu. Marque todas as caixas.
O Hub Redondo, o Hub Paisagem e a TV Fullscreen são selecionados por padrão e devem ser suportados. Cada um desses é uma tela que você oficialmente vai suportar. O conteúdo não se ajustará a elas, então os ativos e o layout de APL que você enviar na resposta serão exibidos como estiverem. Isso também significa que os perfis de janela de visualização que não forem suportados vão ajustar o conteúdo à janela de visualização de tamanho mais próximo que você suportar. Selecione todos, pois você vai verificar e testar cada um desses perfis. Ao selecioná-los, você está dizendo que testou o layout em cada perfil. Para aprender mais sobre a seleção de perfis de janela de visualização, confira a documentação técnica.
C. Depois de ativar a APL e selecionar todos os perfis de janela de visualização, você deve compilar o modelo de interação. Observação: isso também significa que fazer mudanças nos perfis suportados exige uma nova rodada de certificação na nova skill para que sejam publicados.
D. Depois de compilar, você está pronto para testar. Vá para a aba de testes e confira se a opção “Device Display” (Exibição do Dispositivo) está marcada. Rolando a tela até depois da solicitação/resposta do json, você pode selecionar o dispositivo que quer testar. Desmarque a Skill I/O (Entrada/Saída da Skill) para não precisar rolar a tela para ver os elementos visuais!
Lembre-se de apagar seus dados de usuário, se houver! Como modificamos o handler de inicialização sem contexto, você deve deletar os dados de usuário do S3 para que não haja mesmo nenhum contexto na hora de testar a nova tela.
E. Teste a tela no Hub Médio ativando o handler de inicialização, digitando, por exemplo, open cake time.
F. Repita esse teste em todos os tipos de telas. Lembre-se de que não incluímos a imagem do bolo de aniversário ainda, então não se preocupe se ela não estiver aparecendo!
Antes de usarmos ativos de imagem, precisamos hospedá-las. Use, de preferência, um CDN (como o Amazon Cloudfront, junto com o S3) para oferecer seus ativos em locais mais perto dos usuários, mas, para este exercício, usaremos o S3, pois ele é fornecido pela Alexa.
A. Para fazer upload de Ativos de S3, acesse o S3, na aba Code (Código), no canto inferior esquerdo.
B. Na provisão do S3, abra a página media (mídia).
C. Faça o upload de todos os ativos desta página. Para facilitar, os arquivos compactados estão aqui. Vamos usar todos durante o módulo. Após o upload, você verá todos os ativos na página no S3.
Agora que você já fez o upload dos ativos, podemos atualizar a solicitação de inicialização com mais imagens.
Agora que a solicitação de inicialização sem contexto está funcionando, é hora de adicionar uma imagem de fundo no lugar do fundo padrão.
A. Para isso, abra a authoring tool (ferramenta de criação) e cole as informações do launchDocument.json.
B. Na seção de dados da authoring tool, use:
{
"text": {
"start": "Welcome",
"middle": "to",
"end": "Cake Time!"
},
"assets": {
"cake":"https://github.com/alexa/skill-sample-nodejs-first-apl-skill/blob/master/modules/assets/alexaCake_960x960.png?raw=true",
"backgroundURL": "https://github.com/alexa/skill-sample-nodejs-first-apl-skill/blob/master/modules/assets/lights_1920x1080.png?raw=true"
}
}
Você deve estar vendo um novo campo nos dados, o backgroundURL, sob o objeto de ativos, representando de onde o dispositivo buscará uma imagem de fundo. Usaremos o repositório do GitHub para hospedagem enquanto desenvolvemos a tela, por ser um link público, mas nosso código real usará a função utilitária de link pré-definida do S3. A função utilitária de link pré-definida é necessária para gerar uma URL pública de curta duração para o bucket privado para onde você fez upload dos ativos. Agora precisamos adicionar o componente de fundo.
C. Vá para a aba APL da authoring tool.
D. Vamos adicionar o componente responsivo AlexaBackground. Para usá-lo, você precisa do pacote alexa-layouts que já tem! É fácil usar o AlexaBackground. Basta incluir o seguinte no topo dos contêineres, na array (matriz) de itens de cada um:
{
"type": "AlexaBackground",
"backgroundImageSource": "${assets.backgroundURL}"
},
Você deve estar vendo o fundo se acender... Opa... Veja as luzes no fundo.
E. Agora que estamos usando uma imagem de fundo, vamos mudar a cor do texto. Como já temos um estilo para todos os objetos de texto, vai ser fácil! Basta adicionar "color": "black", como uma nova propriedade no estilo bigText. Com isso, você terá:
"bigText": {
"values": [
{
"fontSize": "72dp",
"color": "black",
"textAlign": "center"
}
]
}
F. Aplique as mesmas mudanças na @hubRoundSmall e tenha certeza de que ela funciona na authoring tool.
Lembre-se de deixar o componente responsivo AlexaBackground acima dos demais componentes, se não eles são ocluídos!
Você deve ter notado que estamos usando um único arquivo .png de 1920x1080 para todos os dispositivos e que ele se ajusta muito bem. Queremos usar a maior resolução possível para abarcar os dispositivos FireTV. A redução produz mais qualidade de imagem. Em compensação, dispositivos com menor resolução, que não suportam esse nível de qualidade, vão baixar dados desnecessários. O melhor é fornecer duas ou mais resoluções de imagem para diferentes classes de dispositivos. Veremos como fazer isso na próxima seção.
A. Agora que o documento está pronto, substitua o conteúdo do launchDocument.json pelo JSON da authoring tool, na aba Code (Código).
B. Volte para o index.js. Como estamos adicionando links à instância S3 privada, precisamos importar o módulo de utilitários. No topo do arquivo, adicione outra importação:
const util = require('./util');
C. Adicione novas fontes de dados ao código, no index.js. Como as imagens estão no bucket não público do S3, vamos usar a função utilitária para obter uma URL pública de curta duração para o ativo. As chaves do objeto S3, neste caso, serão da forma , 'Media/imageName.png'. Vamos incluir as imagens nos dados do bloco da APL. O bloco de fontes de dados deve estar parecido com isto:
datasources: {
text: {
type: 'object',
start: "Welcome",
middle: "to",
end: "Cake Time!"
},
assets: {
cake: util.getS3PreSignedUrl('Media/alexaCake_960x960.png'),
backgroundURL: util.getS3PreSignedUrl('Media/lights_1920x1080.png')
}
}
D. Implemente e teste o novo documento em cada tamanho de tela.
E. Está funcionando? Ainda não acabamos! Vamos adicionar a otimização que mencionamos na última seção. Para isso, precisamos de outro ativo. Já fizemos o upload do lights_1280x800.png. Precisamos trocar as imagens para, condicionalmente, trazer o ativo correto. Substitua o valor da backgroundURL por:
util.getS3PreSignedUrl(backgroundKey)
F. Para definir condicionalmente backgroundKey, correta, precisamos usar o Ask-sdk-core, que já importamos como Alexa. Para obter a janela de visualização, adicione, dentro da condicional da APL:
const viewportProfile = Alexa.getViewportProfile(handlerInput.requestEnvelope);
G. Podemos implementar essa lógica com a instrução adicionada abaixo da instrução viewportProfile:
const backgroundKey = viewportProfile === 'TV-LANDSCAPE-XLARGE' ? "Media/lights_1920x1080.png" : "Media/lights_1280x800.png";
H. Faça o teste e lembre-se de usar a TV e os dispositivos Hub no console de testes. Talvez você não veja muita diferença. Se quiser verificar se está funcionando, dê uma olhada na seção Skill I/O, no console de testes, e verifique se os ativos são apresentados corretamente quando você usa uma TV vs. um dispositivo com resolução menor.
Como nosso front-end está se ajustando corretamente, usando os componentes responsivos, nosso trabalho acabou! Vamos para o próximo módulo para aprender mais conceitos avançados de documentos APL.
