Como adicionar produtos In-Skill à sua habilidade Alexa

Garrett Vargas Blocked Desbloquear Seguir Seguindo 26 de dezembro

Como a Amazon anunciou a capacidade de oferecer compras em habilidades para desenvolvedores que criam habilidades em Alexa, adicionei quatro partes de conteúdo premium a duas habilidades diferentes. Recentemente, publiquei um artigo sobre por que você deve considerar a adição de conteúdo premium e, neste artigo, acompanho amostras de código passo a passo para mostrar exatamente como você pode fazer isso por meio do SDK do ASK.

Tipos de produtos em habilidades

Antes de entrar no código, quero revisar os tipos de produtos (ou ISPs) que a Amazon disponibilizou para o Alexa, as diferentes maneiras de expô-los e algumas considerações para ter em mente quando e com que frequência você Informe o seu cliente com lembretes sobre o seu conteúdo.

Existem três tipos de ISPs que sua habilidade pode oferecer:

  • Direitos : são produtos que são basicamente um interruptor on / off. Eles normalmente bloqueiam um recurso dentro de sua habilidade – uma vez que o cliente tenha comprado este produto, ele terá acesso contínuo ao recurso. Normalmente, são recursos como pacotes de expansão, níveis adicionais ou efeitos sonoros premium.
  • Assinatura : Uma assinatura fornece acesso a um recurso ou conteúdo, mas, diferentemente de um direito, o cliente paga pelo recurso mensalmente ou anualmente. Uma vez cancelado, o usuário perde o acesso ao recurso premium. Normalmente, você ofereceria uma assinatura para um recurso com conteúdo contínuo em evolução, como acesso a uma biblioteca de músicas ou vídeos. Você também pode oferecer períodos de teste gratuitos com assinaturas.
  • Consumíveis : um consumível é um produto que pode ser comprado, usado e comprado novamente. Exemplos incluem vidas extras ou um número definido de dicas em um jogo.

Uma vez que você tenha decidido que tipo de produto você quer oferecer, você deve pensar em como vai enviar o produto para seus clientes. Você pode fazer isso na descrição da sua página inicial, mas como muitos clientes não leem esse conteúdo completamente, você precisará torná-los cientes dos produtos que oferece por meio de seu conteúdo de voz. A melhor maneira de conscientizar os usuários sobre esse conteúdo e aumentar sua taxa de conversão é fazer isso durante uma parte natural da conversa, em que o conteúdo premium pode ser útil:

  • Se você estiver oferecendo um pacote de expansão com níveis extras para um jogo, convém oferecê-lo quando um usuário recorrente que tenha concluído todos os níveis internos iniciar sua habilidade.
  • Se você está oferecendo um jogo diferente como parte de uma habilidade multi-jogo, você pode querer oferecê-lo quando um usuário tentar mudar de um jogo para outro.
  • Se você está oferecendo vidas ou dicas extras, você pode querer oferecê-las no ponto em que um usuário usou todas as suas vidas ou dicas atuais para continuar jogando.
  • Também é uma prática recomendada ter uma intenção que permita ao cliente explorar o que você tem a oferecer – respondendo a frases como "O que você tem disponível para comprar?"
  • Se um cliente recusou uma oferta de compra de conteúdo premium, você deve entrar em um modo de retirada exponencial – oferecendo o conteúdo com menos frequência nos usos subseqüentes da habilidade. Eu recomendo que você não pare completamente de oferecer seu conteúdo premium. Já vi clientes que recusaram um upsell aceitarem a oferta.

Selecionando uma nova máquina no Slot Machine

Para a amostra de codificação, vou me referir a um dos jogos premium que ofereço para comprar na minha habilidade Slot Machine. Slot Machine permite que os clientes joguem várias máquinas, e eles podem dizer "escolha um jogo diferente" para trocar de uma máquina para outra. Meu conteúdo premium pode ser apresentado ao usuário em um dos três locais – quando eles iniciam a habilidade, quando mudam para uma máquina diferente e depois de reproduzir continuamente a mesma máquina por um determinado período de tempo.

Usando a CLI para adicionar seu produto

Para adicionar um produto na habilidade à sua habilidade do Alexa, você precisa usar o ASK CLI. Se você não usou a CLI, siga as etapas 1 a 3 dessas instruções para configurá-lo. Depois de configurá-lo, você precisará clonar a habilidade à qual deseja adicionar um produto premium. Faça isso com o comando clone

 pergunte clone 

Isso fornecerá uma lista das suas habilidades no Alexa. Use as teclas de seta para selecionar a habilidade que você deseja clonar e aperte enter. A clonagem copiará o manifesto, os metadados e o código da habilidade se você estiver usando uma função do Lambda em sua máquina. Depois de ter essa cópia local, mude para o diretório raiz da habilidade recém-clonada e use este comando para configurar seu produto na habilidade.

 pergunte adicionar isp 

Isso apresentará uma lista de tipos de produtos que você pode adicionar

 Lista de tipos de produtos que você pode escolher (use as teclas de seta) 
> Consumível
Direito
Inscrição

Selecione o que você gostaria de usar e aceite o modelo padrão com o qual você é apresentado. Depois de fazer isso, você será solicitado a digitar o nome do seu novo produto especializado. Suponha que você chame isso de extragame . Isso criará um novo arquivo chamado extragame.json em uma pasta isp na sua habilidade.

Abra este arquivo e você verá vários detalhes que precisa preencher para descrever sua habilidade. Especificamente, você precisará fornecer um nome, uma descrição, ícones (no formato 108×108 e 512×512) e alguns detalhes da release que descrevam o preço e a data de lançamento da oferta do produto. Também vale a pena notar que você precisará fornecer um link para uma política de privacidade para sua habilidade. Não se preocupe, você pode encontrar vários exemplos de políticas que você pode aproveitar pesquisando on-line sobre “política de privacidade de habilidades do Alexa”.

Depois de preencher essas informações, você poderá implantar sua habilidade usando ask deploy que fará o upload das novas configurações do produto para sua habilidade.

Verificando a disponibilidade do produto

Agora que você fez o upload de uma configuração de produto, é necessário adicionar suporte em seu código. A primeira coisa que você deve fazer é usar o MonetizationServiceClient para verificar quais produtos estão disponíveis quando o usuário inicia sua habilidade. O código a seguir mostra como você pode fazer isso e economizar a disponibilidade de cada produto nos atributos da sua sessão:

 const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient (); 
 return ms.getInSkillProducts (event.request.locale) 
.then ((inSkillProductInfo) => {
deixe o estado;
attributes.paid = {};
 if (inSkillProductInfo) { 
inSkillProductInfo.inSkillProducts.forEach ((product) => {
if (product.entitled === 'ENTITLED') {
estado = 'COMPRADO';
} else if (product.purchasable == 'PURCHASABLE') {
estado = 'DISPONÍVEL';
}

if (estado) {
attributes.paid [product.referenceName] = {
productId: product.productId,
estado: estado,
};
}
}
});
})
.catch ((erro) => {
// Ignore erros
});

Agora, dentro do seu objeto attributes.paid , você tem uma lista de todos os produtos, com um estado definido como PURCHASED ou AVAILABLE . Você pode verificar esse objeto quando tentar vender uma oferta de produto para ver se ela já foi comprada ou se está disponível para compra.

Definindo uma Resposta do Upsell

O código para oferecer um produto para compra pode ser um pouco complicado. Basicamente, você vai entregar o pedido de compra para o Alexa, saindo da sessão do usuário no processo. O Alexa cuidará da interação e do fluxo de pagamento com o cliente, inclusive oferecendo descontos que a Amazon pode estar executando no momento. O seu código será então chamado de volta com uma nova sessão e o resultado se o cliente comprou o seu produto ou não.

A resposta Connections.SendRequest ao Alexa inicia esse processo. Felizmente, você pode passar um token como parte dessa resposta, que será retornada para você como parte da nova solicitação de sessão. Achei isso útil e use-o para informar qual produto eu estava oferecendo (lembre-se de que ofereço vários produtos) e qual manipulador me enviou a solicitação (já que posso fazer essa oferta de upsell em vários locais). Isso me permite deixar o usuário de volta no fluxo de interação. Se eles recusarem uma resposta de compra, eu sei o que eles estavam tentando fazer antes de interrompê-los com uma oferta, para que eu possa devolvê-los onde estavam. Se eles aceitaram a compra, também tenho o contexto para poder soltá-los na parte apropriada do código. Por exemplo, se o usuário estiver vendendo uma máquina caça-níqueis com tema de feriado durante o processo de seleção de um novo jogo, usaria um token chamado holiday.select

Veja como é o código:

 // Cria uma diretiva upsell 
diretiva const = {
'type': 'Connections.SendRequest',
'name': 'Upsell',
'payload': {
'InSkillProduct': {
productId: attributes.paid [upsellProduct] .productId,
}
'upsellMessage': 'Temos um jogo temático de fim de ano disponível para compra, queremos ouvir mais?',
}
'token': 'holiday.select',
};
 return handlerInput.responseBuilder 
.addDirective (directiva)
.withShouldEndSession (true)
.getResponse ();

Observe que o campo upsellMessage precisa estar em texto sem formatação. Quaisquer tags SSML que você definir para diferentes vozes ou variação de fala serão ignoradas quando lidas pelo Alexa. Do ponto de vista da interação com o cliente, o que eles ouvirão é algo assim – note que depois que o usuário disser sim para o upsellMessage definido pelo seu código, a interação é tratada diretamente pelo Alexa:

Alexa, selecione uma nova máquina
Temos um jogo temático de fim de ano disponível para compra, quer ouvir mais?
sim
Isso adicionará o Holiday Game à lista de máquinas caça-níqueis que você pode jogar. Membros principais economizam US $ 0,19. Sem Prime, seu preço é de US $ 0,99, mais impostos. Você gostaria de comprá-lo?
sim
Por favor, diga o seu código de 4 dígitos para confirmar a compra.

Se você está lidando com uma compra explícita ao contrário de um upsell (ou seja, respondendo a uma solicitação como "Alexa, compre o jogo de fim de ano"), defina o name na diretiva para "Comprar" e remova o campo upsellMessage . Você ainda vai querer definir o token para que você possa lidar com a resposta quando eles retornarem à sua habilidade.

E não se esqueça da mensagem de cancelamento! Novamente, como no caso da compra, você precisará dar suporte a uma declaração que permita ao cliente reembolsar a compra (“Alexa, reembolsar o jogo de férias”). Para esta mensagem, você define o name na diretiva para 'Cancelar' e novamente remove o campo upsellMessage .

Processando a Resposta do Usuário

Se o usuário disser sim ou não à sua solicitação de upsell, ou se houver algum outro erro durante o fluxo de compra, sua habilidade será invocada com uma nova sessão com um tipo de solicitação de Connections.Response Você pode então levar o usuário para qualquer ponto de continuação para eles é. Se eles ouvirem essa mensagem enquanto selecionam uma nova máquina e fizerem a compra, eu a deixo na máquina selecionada e pronta para jogar. Se eles recusarem a compra, eu digo quais outras máquinas que temos disponíveis para que possam continuar o processo de seleção de uma nova máquina. Se houve algum tipo de erro durante a compra, eu os coloquei no mesmo fluxo como se eles tivessem recusado a compra. O Alexa vai lidar com a informação de que houve um erro, então não há necessidade de o nosso código repetir isso. O manipulador da resposta é assim:

 canHandle: function (handlerInput) { 
const request = handlerInput.requestEnvelope.request;
return (request.type === 'Connections.Response');
}
handle: function (handlerInput) {
const event = handlerInput.requestEnvelope;
atributos de atributos = handlerInput.attributesManager.getSessionAttributes ();
 // options [0] será o nome do jogo que vendemos 
// options [1] será a intenção em que foram vendidos
const options = event.request.token.split ('.');
const accepted = (event.request.payload &&
((event.request.payload.purchaseResult == 'ACEITO') ||
(event.request.payload.purchaseResult == 'ALREADY_PURCHASED')));
vamos nextAction = opções [1];
 if ((event.request.name === 'Upsell') &&! aceito) { 
// Não os use novamente na próxima rodada
attributes.noUpsell = true;
}
 // Eles aceitaram? 
if (aceito) {
// Se este for um cancelamento, remova-o
if (event.request.name === 'Cancelar') {
atributos [opções [0]] = indefinido;
if (attributes.paid && attributes.paid [opções [0]]) {
attributes.paid [opções [0]]. state = 'AVAILABLE';
}
} outro {
// Vamos selecionar automaticamente
// Certifique-se de colocá-lo na lista de produtos pagos conforme comprados
if (attributes.paid && attributes.paid [opções [0]]) {
attributes.paid [opções [0]]. state = 'COMPRADO';
}
nextAction = 'autoselect';
}
}
 // E vá para o próximo passo apropriado 
// Select, SelectYes, Spin e Launch são manipuladores de intenção
if (nextAction === 'selecionar') {
return Select.handle (handlerInput);
} else if (nextAction === 'autoselect') {
attributes.gameToSelect = opções [0];
return SelectYes.handle (handlerInput);
} else if (nextAction === 'girar') {
return Spin.handle (handlerInput);
} outro {
// Basta colocá-los diretamente em um jogo
return Launch.handle (handlerInput);
}

Você notará que, além de configurar a nova máquina, se selecionada e transferida para a próxima intenção apropriada de processamento, há um código que define um sinalizador noUpsell se o usuário recebeu uma mensagem de venda com noUpsell e a recusou. Isso é para evitar um loop infinito, uma vez que eu coloco o usuário de volta no mesmo caminho em que estavam anteriormente. Antes de apresentar uma mensagem upsell, meu código verifica se esse sinalizador está configurado para evitar um loop infinito. Isso também ajuda a garantir que os clientes só recebam uma mensagem upsell uma vez durante a sessão, proporcionando uma melhor experiência ao cliente.

Espero que você tenha achado este guia útil, e boa sorte ao adicionar conteúdo premium às suas próprias habilidades em Alexa!