Este guia explica como adicionar transações digitais à sua conversa. Ação para que os usuários possam comprar seus bens digitais consumíveis.
Termos-chave: um produto digital consumível é uma unidade de manutenção de estoque (SKU) que Um usuário pode usar e comprar mais de uma vez, como uma quantidade de moeda do jogo para um jogo Android. Esse bem digital é diferente de um produto não consumível. produto digital que o usuário só pode comprar uma vez.
Para mais informações sobre produtos de aquisição única, consulte a documentação documentação sobre recursos específicos de produtos de aquisição única.
Fluxo de transações
Este guia descreve cada etapa de desenvolvimento conforme elas ocorrem em um produto digital fluxo de transações. Quando sua Ação lida com transações de produtos e softwares digitais, usa este fluxo:
- Configurar um cliente de API de compras digitais: sua ação usa o a API de compras para se comunicar com seu inventário do Google Play e realizar transações. Antes de qualquer outra ação, a ação cria um cliente JWT com uma chave de serviço para se comunicar com a API Digital Purchases.
- Coletar informações: a ação coleta informações básicas sobre o
usuário e seu inventário do Google Play a fim de se preparar para uma transação.
- Validar os requisitos de transação: sua ação usa o do assistente de requisitos de transações no início do fluxo de compra para para garantir que o usuário possa fazer transações.
- Coletar inventário disponível: a ação verifica o inventário do Google Play. inventário e identifica quais itens estão disponíveis para compra no momento.
- Criar o pedido: sua ação apresenta os produtos e softwares digitais disponíveis para o usuário para que ele possa selecionar um para comprar.
- Concluir a compra: sua ação usa a API de compras digitais para iniciar uma compra com a seleção do usuário na Google Play Store.
- Gerencie o resultado: sua ação recebe um código de status para o transação e notifica o usuário de que a compra foi bem-sucedida (ou leva etapas adicionais).
- Tornar a compra repetível: a ação usa as compras digitais. API para "consumir" o item comprado, tornando-o disponível para compra novamente por esse usuário.
Restrições e diretrizes de avaliações
Outras políticas são aplicáveis a ações com transações. Podemos levar alguns para analisar as ações que incluem transações. Por isso, considere o tempo planejar sua programação de lançamentos. Para facilitar o processo de revisão, verifique se você está em conformidade com o políticas e diretrizes para transações antes de enviar sua Ação para revisão.
As ações que vendem produtos e softwares digitais só podem ser implantadas nos seguintes países:
- Austrália
- Brasil
- Canadá
- Indonésia
- Japão
- México
- Rússia
- Singapura
- Tailândia
- Turquia
- Reino Unido
- Estados Unidos
Pré-requisitos
Antes de incorporar transações digitais à sua ação, você precisa do seguintes pré-requisitos:
Um conta de desenvolvedor e um conta do comerciante no Google Play, para gerenciar seus produtos e softwares digitais na Google Play Console:
Um domínio da Web que é verificadas no Google Search Console. Esse domínio não precisa estar associado a um site lançado publicamente. só precisamos fazer referência ao seu domínio da Web.
Um app Android com o
com.android.vending.BILLING
permissão no Google Play Console. Seus produtos e softwares digitais serão "compras no app" associadas a ele no Google Play Console.Você também precisa criar uma versão no Play Console com esse app. No entanto, se você não quiser que a versão seja pública, crie uma versão Alfa fechada lançamento.
Se você ainda não tem um app Android, siga as Instruções para associar um app Android.
Um ou mais produtos gerenciados na Google Play Console, que são os produtos e softwares digitais que você vende com a ação. Observe que você não é possível criar produtos gerenciados no Play Console até que você configure o Pré-requisito do app Android.
Se você ainda não tem produtos gerenciados, siga as Instruções para criar produtos digitais.
Associar um app Android
Se você não tem um app Android com a permissão de faturamento na Google Play Console, siga estas etapas:
- No Android Studio ou o ambiente de desenvolvimento integrado do Android de sua escolha, crie um novo projeto. Escolher opções em os comandos de configuração do projeto para criar um app muito básico.
- Dê um nome de pacote ao projeto, como
com.mycompany.myapp
. Não deixe esse nome como padrão, já que não é possível carregar pacotes que incluemcom.example
ao Play Console. - Abra o arquivo
AndroidManifest.xml
do app. Adicione a linha de código abaixo no elemento
manifest
:<uses-permission android:name="com.android.vending.BILLING" />
O arquivo
AndroidManifest.xml
vai ficar parecido com este bloco de código:<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" package="com.mycompany.myapp"> <uses-permission android:name="com.android.vending.BILLING" /> <application android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:roundIcon="@mipmap/ic_launcher_round" android:supportsRtl="true" android:theme="@style/AppTheme" /> </manifest>
Crie o app como um APK assinado. No Android Studio, siga estas etapas:
- Acesse Build e Generate Signed Bundle / APK.
- Clique em Próxima.
- Em Caminho do repositório de chaves, clique em Criar novo.
- Preencha todos os campos e clique em OK. Anote as informações do seu Keystore senha e Senha da chave e armazene-as em um local seguro, já que você vai usá-las mais tarde.
- Clique em Próxima.
- Selecione lançar.
- Selecione V1 (assinatura JAR).
- Clique em Finish.
- Após alguns segundos, o Android Studio gera um arquivo
app-release.apk
. Localize o arquivo para uso posterior.
Na Google Play Console, criar um novo aplicativo.
Acesse Versões de apps.
Em Faixas fechadas, acesse Gerenciar e Alfa.
Clique no botão Criar versão.
Em Deixar o Google gerenciar e proteger sua chave de assinatura, digite sua assinatura informações importantes.
Faça o upload do seu arquivo APK.
Clique em Salvar.
Crie seus produtos digitais
Se você não tiver produtos e softwares digitais no Play Console no momento, siga estas instruções etapas:
- Na Google Play Console, Acesse Produtos no app e depois Produtos gerenciados. Se você receber um aviso, siga as instruções anteriores para criar um app Android ou clique no link para criar um perfil de comerciante.
- Clique em Criar um produto gerenciado.
- Preencha os campos do seu produto digital. Anote o ID do produto, que é como você vai referenciar esse produto na sua ação.
- Clique em Salvar.
- Repita as etapas de 2 a 4 para cada produto que você quer vender.
Preparar seu projeto do Actions
Com seus produtos e softwares digitais configurados no Google Play Console, você precisa ativar transações digitais e associar o projeto do Actions ao app do Google Play.
Configuração
Para ativar as transações de produtos e softwares digitais no seu projeto do Actions, siga estas instruções etapas:
- No Console do Actions, abra ou crie um projeto.
- Acesse Implantar e Informações do diretório.
- Em Informações adicionais e Transações, marque a caixa Sim. em Suas ações usam a API Digital Purchase para realizar transações de produtos e softwares digitais.
- Clique em Salvar.
Criar uma chave de API de produtos e softwares digitais
Para enviar solicitações à API de produtos e softwares digitais, você precisa fazer o download de um serviço JSON chave da conta associada ao seu projeto do Console do Actions.
Para recuperar a chave da conta de serviço, siga estas etapas:
- No Console do Actions, clique no ícone de três pontos no canto superior direito. e, em seguida, Configurações do projeto.
- Encontre o ID do projeto da sua ação.
- Siga este link, substituindo "
<project_id>
" pelo ID do seu projeto:https://console.developers.google.com/apis/credentials?project=project_id
- Na navegação principal, acesse Credenciais.
- Na página exibida, clique em Criar credenciais e em Serviço chave de conta de serviço.
- Acesse Conta de serviço e clique em Nova conta de serviço.
- Dê um nome à conta de serviço, como digitaltransactions.
- Clique em Criar.
- Defina o Papel como Projeto > proprietário.
- Clique em Continuar.
- Clique em Criar chave.
- Selecione o tipo de chave JSON.
- Clique em Criar chave e faça o download da chave JSON da conta de serviço.
Salve essa chave da conta de serviço em um local seguro. Você vai usar essa chave fulfillment para criar um cliente para a API Digital Purchases.
Conectar ao seu inventário do Google Play
Para acessar seus produtos e softwares digitais em um projeto do Actions, associe o seu domínio da Web e app com seu projeto como propriedades conectadas.
Para conectar o domínio e o app da Web do Play Console ao projeto do Actions, siga estas etapas:
- No Console do Actions, acesse Implantar e depois Verificação de marca.
Se você ainda não conectou propriedades, primeiro conecte um site:
- Clique no botão de propriedade da web (</>).
- Digite o URL do seu domínio da Web e clique em Conectar.
O Google envia um e-mail com mais instruções para a pessoa verificado para esse domínio da Web no Google Search Console. Depois que o destinatário seguir essas etapas, o site deverá aparecem em Verificação de marca.
Assim que você tiver pelo menos um site conectado, execute as seguintes etapas para conectar seu app Android:
- No Console do Actions, acesse Implantar e depois Verificação de marca.
- Clique em Conectar aplicativo.
Na página exibida, siga as instruções para verificar sua conta domínio no Play Console. Selecione o app Google Play que contém seu produtos e softwares digitais e insira o URL do domínio da Web exatamente como ele aparece Verificação de marca.
Mais uma vez, o Google envia um e-mail de verificação para o proprietário verificado de o domínio. Depois que eles aprovarem a verificação, seu app do Google Play deverá aparecem em Verificação de marca.
Ative a opção Acessar compras no Google Play.
Criar seu fluxo de compra
Com o projeto do Actions e o inventário de produtos digitais preparados, crie um fluxo de compra de produtos no webhook de fulfillment da conversa.
1. Configurar um cliente de API de compras digitais
No webhook de fulfillment da conversa, crie um cliente JWT com seu serviço
chave JSON da conta de serviço e a
escopo https://www.googleapis.com/auth/actions.purchases.digital
.
O código Node.js a seguir cria um cliente JWT para a API de compras digitais:
const serviceAccount = {'my-file.json'};
const request = require('request');
const {google} = require('googleapis');
const jwtClient = new google.auth.JWT(
serviceAccount.client_email, null, serviceAccount.private_key,
['https://www.googleapis.com/auth/actions.purchases.digital'],
null
);
2. Coletar informações
Antes de o usuário fazer uma compra, a ação coleta informações sobre o capacidade do usuário de fazer compras e quais produtos estão disponíveis no seu inventário.
2. A. Valide os requisitos de compra digital
É uma boa prática garantir que a conta do usuário esteja configurada para realizar
transações antes de dar a elas a opção de fazer uma compra. Você deve
faça a transição para uma cena DigitalPurchaseCheck
, que confere se o usuário foi verificado.
se a transação foi feita em uma plataforma permitida (smart display,
alto-falante inteligente ou Android) e que estão em um local onde
transações são aceitos.
Para criar uma cena de cheque de compra digital, siga estas etapas:
- Na guia Scenes, adicione uma nova cena com o nome
DigitalPurchaseCheck
. - Em Preenchimento de slot, clique em + para adicionar um novo slot.
- Em Selecionar tipo, selecione
actions.type.DigitalPurchaseCheckResult
como o tipo de slot. - No campo de nome do slot, dê o nome
DigitalPurchaseCheck
ao slot. - Marque a caixa de seleção Personalizar o writeback do valor do slot (ativada por padrão).
- Clique em Salvar.
Um cheque de compra digital resulta em um dos seguintes resultados:
- Se os requisitos forem atendidos, o parâmetro de sessão será definido com sucesso e você poderá continuar permitindo que o usuário compre produtos e softwares digitais.
- Se um ou mais requisitos não puderem ser atendidos, o parâmetro session será com uma condição de falha. Nesse caso, você deve dinamizar a conversa da experiência transacional ou encerrar a conversa.
Para processar o resultado de um cheque de compra digital, siga estas etapas:
- Na guia Cenas, selecione a cena
DigitalPurchaseCheck
recém-criada. - Em Condição, clique em + para adicionar uma nova condição.
No campo de texto, digite a seguinte sintaxe de condição para verificar os condição de sucesso:
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
Passe o cursor sobre a condição que você acabou de adicionar e clique na seta para cima. para posicioná-lo antes de
if scene.slots.status == "FINAL"
.Ative Enviar solicitações e forneça um comando simples informando ao usuário. ele está pronto para fazer uma transação:
candidates: - first_simple: variants: - speech: >- You are ready to purchase digital goods.
Em Transição, selecione outra cena que permita ao usuário continuar a conversa e prosseguir com a transação.
Selecione a condição
else if scene.slots.status == "FINAL"
.Ative Enviar solicitações e forneça um comando simples informando ao usuário. ele não consegue fazer uma transação:
candidates: - first_simple: variants: - speech: Sorry you cannot perform a digital purchase.
Em Transição, selecione Encerrar conversa para encerrar a conversa.
2. b. Reunir inventário disponível
Use a API de compras digitais para solicitar a Play Store disponível no momento inventário e transformá-lo em uma matriz de objetos JSON para cada produto. Você vai consultar essa matriz mais tarde para mostrar ao usuário as opções disponíveis para compra.
Cada um dos seus produtos digitais é representado como uma SKU no formato JSON. A o código Node.js a seguir descreve a formatação esperada de cada SKU:
body = {
skus: [
skuId: {
skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
id: string,
packageName: string
}
formattedPrice: string,
title: string,
description: string
]
}
Envie uma solicitação POST ao
https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet
em que {packageName}
é o nome do pacote do app no Google Play
Console (por exemplo, com.myapp.digitalgoods
) e formate o resultado em um
matriz de objetos SKU.
Para recuperar apenas produtos digitais específicos na matriz resultante, liste o produto
Códigos de produtos digitais (conforme exibido em cada produto no app no Google Play)
Console) que você quer disponibilizar para compra no app body.ids
.
O código Node.js a seguir solicita uma lista de produtos disponíveis na API de compras e formata o resultado como uma matriz de SKUs:
return jwtClient.authorize((err, tokens) => {
if (err) {
throw new Error(`Auth error: ${err}`);
}
const packageName = 'com.example.projectname';
request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
'auth': {
'bearer': tokens.access_token,
},
'json': true,
'body': {
'conversationId': conv.session.id,
'skuType': 'SKU_TYPE_IN_APP',
// This request is filtered to only retrieve SKUs for the following product IDs
'ids': ['consumable.1']
},
}, (err, httpResponse, body) => {
if (err) {
throw new Error(`API request error: ${err}`);
}
console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
console.log(JSON.stringify(body));
});
});
});
3. Criar o pedido
Para iniciar a compra digital do usuário, apresente uma lista dos seus produtos e softwares digitais disponíveis para compra. Você pode usar uma variedade tipos de resposta avançada para representar seus estoque e solicitar que o usuário faça uma seleção.
O código Node.js a seguir lê uma matriz de inventário de objetos SKU e cria um resposta de lista com um item da lista para cada:
const items = [];
const entries = [];
skus.forEach((sku) => {
const key = `${sku.skuId.skuType},${sku.skuId.id}`
items.push({
key: key
});
entries.push({
name: key,
synonyms: [],
display: {
title: sku.title,
description: `${sku.description} | ${sku.formattedPrice}`,
}
});
});
conv.session.typeOverrides = [{
name: 'type_name',
mode: 'TYPE_REPLACE',
synonym: {
entries: entries
}
}];
conv.add(new List({
title: 'List title',
subtitle: 'List subtitle',
items: items,
}));
Criar compra com base na seleção do usuário
Depois que o usuário selecionar um item, você poderá criar o pedido. Para isso, mediante o associado ao item selecionado, é possível chamar seu webhook para criar o pedido. No processamento do pedido, salve os dados do pedido em uma sessão . O objeto "order" é usado em várias cenas na mesma sessão.
conv.session.params.purchase = {
"@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
"skuId": {
"skuType": "<SKU_TYPE_IN_APP>",
"id": "<SKU_ID>",
"packageName": "<PACKAGE_NAME>"
},
"developerPayload": ""
};
No Actions Builder, você pode usar o editor JSON para configurar o slot
com o objeto de ordenação acima. As duas implementações usam o mesmo formato para
CompletePurchaseValueSpec
, que pode ser encontrado na
Referência de payload do webhook JSON.
4. Concluir a compra
Depois que o usuário selecionar um item, você poderá concluir a compra. Depois de preencher associado ao item selecionado, faça a transição para uma cena que realiza uma compra completa.
Criar cena completa de compra
- Na guia Cenas, adicione uma cena chamada
CompletePurchase
. - Em Preenchimento de slot, clique em + para adicionar um novo slot.
- Em Selecionar tipo, selecione
actions.type.CompletePurchaseValue
como o tipo de slot. - No campo de nome do slot, dê o nome
CompletePurchase
ao slot. - Marque a caixa de seleção Personalizar o writeback do valor do slot (ativada por padrão).
- Em Configurar slot, selecione
Use session parameter
no menu suspenso. - Em Configurar slot,insira o nome do parâmetro da sessão usado para
armazene o pedido no campo de texto (ou seja,
$session.params.purchase
). - Clique em Salvar.
5. Gerenciar o resultado
Um slot com o tipo actions.type.CompletePurchaseValue
pode ter o seguinte:
resultados:
PURCHASE_STATUS_OK
: a compra foi concluída. A transação é concluir neste ponto, então saia do fluxo transacional e volte para a conversa.PURCHASE_STATUS_ALREADY_OWNED
: a transação falhou porque o usuário já possui esse item. Para evitar esse erro, verifique a configuração compras e personalizar os itens mostrados para que não tenham a opção de comprar novamente itens que já possuem.PURCHASE_STATUS_ITEM_UNAVAILABLE
: a transação falhou porque o O item solicitado não está disponível. Evite esse erro verificando as opções SKUs mais próximos do momento da compra.PURCHASE_STATUS_ITEM_CHANGE_REQUESTED
: a transação falhou porque o o usuário decidiu comprar outra coisa. Reprompt com a criação do seu pedido para que o usuário possa tomar outra decisão imediatamente.PURCHASE_STATUS_USER_CANCELLED
: a transação falhou porque o usuário o fluxo de compra foi cancelado. Como o usuário saiu prematuramente do fluxo, Perguntar ao usuário se ele quer repetir a transação ou sair dela completamente.PURCHASE_STATUS_ERROR
: a transação falhou por um motivo desconhecido. Informe ao usuário que a transação falhou e pergunte se ele quer tentar de novo.PURCHASE_STATUS_UNSPECIFIED
: a transação falhou por um motivo desconhecido, resultando em um status desconhecido. Gerencie esse status de erro permitindo que o o usuário sabe que a transação falhou e pergunte se ele quer tentar novamente.
Gerencie cada um desses resultados da cena CompletePurchase
.
- Na guia Cenas, selecione a cena
CompletePurchase
recém-criada. - Em Condição, clique em + para adicionar uma nova condição.
No campo de texto, digite a seguinte sintaxe de condição para verificar os condição de sucesso:
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
Passe o cursor sobre a condição que você acabou de adicionar e clique na seta para cima. para posicioná-lo antes de
if scene.slots.status == "FINAL"
.Ative Enviar solicitações e forneça um comando simples informando ao usuário. ele está pronto para fazer uma transação:
candidates: - first_simple: variants: - speech: >- Your purchase was successful.
Em Transição, selecione Encerrar conversa para encerrar a conversa.
Repita as etapas acima para cada tipo de resultado de compra que você quer apoiar.
6. Tornar a compra repetível
Após uma transação bem-sucedida, envie uma solicitação POST para as compras digitais
API para consumir o item, permitindo que o usuário o compre novamente. Envie sua
solicitação para https://actions.googleapis.com/v3/conversations/{sessionId}/entitlement:consume
endpoint com o ID da sessão encontrada em session.id
.
Sua solicitação POST também deve incluir o objeto de token de compra associado a
da compra do usuário, encontrada no JSON de solicitação do usuário em
packageEntitlements.entitlements.inAppDetails.inAppPurchaseData.purchaseToken
:
O código a seguir envia uma solicitação consume
para a API Digital Purchases e
informa se a solicitação foi bem-sucedida:
request.post(`https://actions.googleapis.com/v3/conversations/${conv.session.id}/entitlement:consume`, {
'auth': {
'bearer': tokens.access_token,
},
'json': true,
'body': {
// This purchase token is in both the purchase event and the user's entitlements
// in their request JSON
"purchaseToken": entitlement.purchaseToken
},
}, (err, httpResponse, body) => {
if (err) {
throw new Error(`API request error: ${err}`);
}
console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
console.log(JSON.stringify(httpResponse));
console.log(JSON.stringify(body));
resolve(body);
});
// Make sure the consume request was successful. In production, don't notify the user; handle failures on the back end
return consumePromise.then(body => {
const consumed = Object.keys(body).length === 0;
if (consumed) {
conv.add(`You successfully consumed ${id}`);
} else {
conv.add(`Failed to consume: ${id}`);
}
});
Reflita as compras do usuário
Quando um usuário consulta sua ação, o objeto user
da solicitação JSON inclui um
lista de compras. Confira essas informações e altere os critérios
com base no conteúdo pago pelo usuário.
O exemplo de código a seguir mostra o objeto user
de uma solicitação que inclui
packageEntitlements
das compras no app feitas anteriormente para o
Pacote com.digitalgoods.application
:
{
"handler": {
"name": "handler_name"
},
"intent": {
"name": "actions.intent.MAIN",
"params": {},
"query": ""
},
"scene": {
"name": "SceneName",
"slotFillingStatus": "UNSPECIFIED",
"slots": {}
},
"session": {
"id": "example_session_id",
"params": {},
"typeOverrides": []
},
"user": {
"locale": "en-US",
"params": {
"verificationStatus": "VERIFIED"
"packageEntitlements": [
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "non-consumable.1",
"skuType": "SKU_TYPE_IN_APP"
}
{
"sku": "consumable.2",
"skuType": "SKU_TYPE_IN_APP"
}
]
},
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "annual.subscription",
"skuType": "SKU_TYPE_SUBSCRIPTION",
"inAppDetails": {
"inAppPurchaseData": {
"autoRenewing": true,
"purchaseState": 0,
"productId": "annual.subscription",
"purchaseToken": "12345",
"developerPayload": "HSUSER_IW82",
"packageName": "com.digitalgoods.application",
"orderId": "GPA.233.2.32.3300783",
"purchaseTime": 1517385876421
},
"inAppDataSignature": "V+Q=="
}
}
]
}
]
}
},
"homeStructure": {
"params": {}
},
"device": {
"capabilities": [
"SPEECH",
"RICH_RESPONSE",
"LONG_FORM_AUDIO"
]
}
}
Testar seu projeto
Ao testar seu projeto, você pode ativar o modo sandbox no Console do Actions para testar a ação sem fazer cobranças na forma de pagamento. Para ativar o modo sandbox, siga estas etapas:
- No Console do Actions, clique em Testar na navegação.
- Clique em Configurações.
- Ative a opção Sandbox de desenvolvimento.