Criar transações de assinatura digital

Neste guia, explicamos como adicionar transações de assinatura digital à ação de conversa para que os usuários possam comprá-las.

Termos-chave: um bem digital de assinatura é uma unidade de manutenção de estoque (SKU) que requer uma cobrança recorrente para um usuário, como uma revista on-line. Ele é diferente de um bem digital consumível que um usuário precisa comprar novamente manualmente ou um produto digital não consumível que é comprado automaticamente apenas uma vez.

Para mais informações sobre assinaturas digitais, consulte a documentação do Android sobre recursos específicos de assinaturas.

Fluxo de transações

Neste guia, descrevemos cada etapa de desenvolvimento à medida que elas ocorrem em um fluxo de transação de mercadorias digitais. Quando sua ação processa transações de produtos e softwares digitais, ela usa o seguinte fluxo:

1. Configurar um cliente de API de compras digitais: sua ação usa a API de compras digitais para se comunicar com seu inventário do Google Play e realizar transações. Antes de sua ação fazer qualquer outra coisa, ele cria um cliente JWT com uma chave de serviço para se comunicar com a API de compras digitais.
2. Coletar informações: sua ação coleta informações básicas sobre o usuário e o inventário do Google Play para se preparar para uma transação.
   1. Validar os requisitos de transação: sua ação usa o auxiliar de requisitos de transações digitais no início do fluxo de compra para garantir que o usuário possa fazer transações.
   2. Coletar inventário disponível: a ação verifica o inventário do Google Play e identifica quais itens estão disponíveis para compra no momento.
3. Criar o pedido: seu Action apresenta os produtos digitais disponíveis ao usuário para que ele possa selecionar um para comprar.
4. Conclua 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.
5. Gerencie o resultado: sua ação recebe um código de status para a transação e notifica o usuário de que a compra foi bem-sucedida (ou realiza etapas adicionais).

Restrições e diretrizes de revisão

Políticas adicionais se aplicam a Ações com transações. A revisão das ações que incluem transações pode levar algumas semanas. Portanto, leve esse tempo em consideração ao planejar sua programação de lançamentos. Para facilitar o processo de revisão, verifique se você está em conformidade com as 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

Observação: durante o processo de revisão, é possível ver transações realizadas por usuários desconhecidos. Esses usuários são associados ao Google como parte do processo de revisão de ação das transações. Sua ação não estará disponível ao público em geral até que seja totalmente analisada e publicada.

Pré-requisitos

Antes de incorporar transações digitais na sua ação, você precisa dos pré-requisitos a seguir:

• Uma conta de desenvolvedor e uma conta de comerciante no Google Play para gerenciar seus produtos e softwares digitais no Google Play Console.

• Um domínio da Web verificado no Google Search Console. Esse domínio não precisa estar associado a um site lançado publicamente, basta fazer referência ao seu domínio da Web.

• Um app Android com a permissão com.android.vending.BILLING no Google Play Console. Seus produtos e softwares digitais são "compras no app" associadas a esse app no Google Play Console.

  Também é necessário criar uma versão no Play Console com esse app. No entanto, se você não quiser que ela seja pública, poderá criar uma versão Alfa fechada.

  Se você ainda não tem um app para Android, siga as instruções para associar um app Android.

• Uma ou mais assinaturas no Google Play Console, que são os produtos e softwares digitais vendidos com o Action. Não será possível criar assinaturas no Play Console até que você configure o pré-requisito do app Android.

  Se você ainda não tiver assinaturas, siga as instruções para criar produtos digitais.

Associar um app Android

Se você não tiver um app Android com a permissão de faturamento no Google Play Console, siga estas etapas:

1. No Android Studio ou no ambiente de desenvolvimento integrado Android de sua escolha, crie um novo projeto. Escolha opções nas solicitações de configuração do projeto para criar um aplicativo muito básico.
2. Dê ao projeto um nome de pacote, como com.mycompany.myapp. Não deixe esse nome como padrão, já que não é possível fazer upload de pacotes que incluam com.example no Play Console.
3. Abra o arquivo AndroidManifest.xml do app.

4. Adicione a seguinte linha de código ao 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>
   

5. Crie seu app como um APK assinado. No Android Studio, siga estas etapas:

   1. Acesse Build, Generate Signed Bundle / APK.
   2. Clique em Próxima.
   3. Em Caminho do armazenamento de chaves, clique em Criar novo.
   4. Preencha todos os campos e clique em OK. Anote a senha do armazenamento de chaves e a senha da chave e armazene-as em um local seguro, pois elas serão usadas mais tarde.
   5. Clique em Próxima.
   6. Selecione Liberar.
   7. Selecione V1 (Assinatura JAR).
   8. Clique em Finish.
   9. Após alguns segundos, o Android Studio gera um arquivo app-release.apk. Localize esse arquivo para uso posterior.

6. No Google Play Console, crie um novo aplicativo.

7. Acesse Versões de apps.

8. Em Faixas fechadas, acesse Gerenciar e Alfa.

9. Clique no botão Criar uma versão.

10. Em Permitir que o Google gerencie e proteja sua chave de assinatura, insira as informações dessa chave.

11. Faça o upload do arquivo APK.

12. Clique em Salvar.

Criar produtos digitais

Se você não tiver produtos e softwares digitais no Play Console, siga estas etapas:

1. No Google Play Console, acesse Produtos no app e Assinaturas. Se um aviso for exibido, siga as instruções anteriores para criar um app para Android ou clique no link para criar um perfil de comerciante.
2. Clique em Criar assinatura.
3. Preencha os campos do seu produto digital. Anote o ID do produto, que é como você fará referência a esse produto na sua ação.
4. Clique em Salvar.
5. Repita as etapas de 2 a 4 para cada produto que você quer vender.

Preparar seu projeto do Actions

Depois de configurar os produtos e softwares digitais no Google Play Console, é necessário ativar as transações digitais e associar o projeto do Actions ao app Google Play.

Configuração

Para ativar as transações de produtos e softwares digitais no seu projeto do Actions, siga estas etapas:

1. No Console do Actions, abra seu projeto ou crie um novo.
2. Acesse Implantar e Informações do diretório.
3. Em Informações adicionais e Transações, marque a caixa Sim em Suas ações usam a API de compra digital para realizar transações de mercadorias digitais.
4. 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 uma chave da conta de serviço JSON associada ao seu projeto do Console do Actions.

Observação: se você estiver usando o Google Cloud para hospedar o fulfillment, não será necessário criar e fazer o download de uma chave de conta de serviço. Com o Application Default Credentials, a variável de ambiente precisa estar disponível no ambiente de execução.

Para recuperar a chave da conta de serviço, siga estas etapas:

1. No Console do Actions, clique no ícone de três pontos no canto superior direito e em Project settings.
2. Encontre o ID do projeto da sua ação.
3. Acesse este link, substituindo "<project_id>" pelo ID do seu projeto: https://console.developers.google.com/apis/credentials?project=project_id
4. Na navegação principal, acesse Credenciais.
5. Na página exibida, clique em Criar credenciais e, em seguida, em Chave da conta de serviço.
6. Acesse Conta de serviço e clique em Nova conta de serviço.
7. Dê um nome à conta de serviço, como digitaltransactions.
8. Clique em Criar.
9. Defina o Papel como Projeto > Proprietário.
10. Clique em Continuar.
11. Clique em Criar chave.
12. Selecione o tipo de chave JSON.
13. Clique em Criar chave e faça o download da chave da conta de serviço JSON.

Salve a chave da conta de serviço em um local seguro. Você usará essa chave no fulfillment para criar um cliente para a API de compras digitais.

Conectar-se ao seu inventário do Google Play

Para acessar seus produtos e softwares digitais de um projeto do Actions, associe o domínio da Web e o app ao projeto como propriedades conectadas.

Observação: as etapas de conexão podem levar até uma semana para serem concluídas enquanto verificamos suas propriedades. Se o site ou app não for vinculado após esse período, entre em contato com o suporte.

Para conectar o app e o domínio da Web do Play Console ao projeto do Actions, siga estas etapas:

1. No Console do Actions, acesse Implantar e Verificação da marca.

2. Se você ainda não conectou nenhuma propriedade, primeiro conecte um site:

   1. Clique no botão da propriedade da web (</>).
   2. Digite o URL do domínio da Web e clique em Conectar.

   O Google envia um e-mail com mais instruções para a pessoa que foi verificada para esse domínio da Web no Google Search Console. Depois que o destinatário deste e-mail seguir essas etapas, o site deverá aparecer em Verificação de marca.

3. Depois de conectar pelo menos um site, execute as seguintes etapas para conectar seu app Android:

   1. No Console do Actions, acesse Implantar e Verificação da marca.
   2. Clique em Conectar aplicativo.

   3. Na página exibida, siga as instruções para verificar seu domínio da Web no Play Console. Selecione o app do Google Play que contém seus produtos digitais e insira o URL do domínio da Web exatamente como mostrado na página Verificação de marca.

      Novamente, o Google envia um e-mail de verificação para o proprietário verificado do domínio. Depois que eles aprovarem a verificação, o app Play deverá aparecer em Verificação de marca.

      Observação: seu domínio da Web aparecerá no Play Console antes de aparecer no Console do Actions. Pode levar vários dias para que o console do Actions seja atualizado.

   4. Ative Acessar compras no Google Play.

Crie seu fluxo de compra

Com o projeto do Actions e o inventário de produtos digitais preparados, crie um fluxo de compra de produtos e softwares digitais no webhook de atendimento da conversa.

1. Configurar um cliente da API de compras digitais

No webhook de fulfillment da conversa, crie um cliente JWT com a chave JSON da conta de serviço e o 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
  );

Observação: veja mais detalhes e etapas detalhadas de instalação na página do GitHub da biblioteca de cliente da API do Google.

2. Coletar informações

Para que o usuário possa fazer uma compra, sua ação coleta informações sobre a capacidade do usuário de fazer compras e quais produtos estão disponíveis no seu inventário.

2. a. Validar requisitos de transação

Recomendamos que a conta do usuário esteja configurada para realizar transações antes de oferecer a opção de fazer uma compra. Você precisa fazer a transição para uma cena DigitalPurchaseCheck, que verifica se o usuário está verificado, se está realizando a transação em uma superfície permitida (smart display, alto-falante inteligente ou Android) e se está em uma localidade compatível com transações digitais.

Para criar uma cena de verificação de compra digital, siga estas etapas:

1. Na guia Cenas, adicione uma nova cena com o nome DigitalPurchaseCheck.
2. Em Preenchimento de slot, clique em + para adicionar um novo slot.
3. Em Selecionar tipo, selecione actions.type.DigitalPurchaseCheckResult como o tipo de slot.
4. No campo "Nome do slot", dê o nome DigitalPurchaseCheck.
5. Marque a caixa de seleção Personalizar valor de gravação do slot (ativada por padrão).
6. Clique em Salvar.

Uma verificação de compra digital resultará em um dos seguintes resultados:

• Se os requisitos forem atendidos, o parâmetro de sessão será definido com uma condição de sucesso e você poderá permitir que o usuário compre produtos digitais.
• Se um ou mais dos requisitos não puderem ser atendidos, o parâmetro de sessão será definido com uma condição de falha. Nesse caso, é necessário abandonar a conversa da experiência transacional ou encerrá-la.

Para gerenciar um resultado da verificação de compra digital, siga estas etapas:

1. Na guia Cenas, selecione a cena DigitalPurchaseCheck recém-criada.
2. Em Condição, clique em + para adicionar uma nova condição.

3. No campo de texto, insira a seguinte sintaxe de condição para verificar a condição:

   scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
   

4. Passe o cursor sobre a condição que você acabou de adicionar e clique na seta para cima para colocá-la antes de if scene.slots.status == "FINAL".

5. Ative Enviar solicitações e forneça uma solicitação simples informando ao usuário que ele está pronto para fazer uma transação:

   candidates:
     - first_simple:
         variants:
           - speech: >-
               You are ready to purchase digital goods.
   

6. Em Transição, selecione outra cena, permitindo que o usuário continue a conversa e continue fazendo uma transação.

7. Selecione a condição else if scene.slots.status == "FINAL".

8. Ative a opção Enviar solicitações e forneça um aviso simples informando ao usuário que não foi possível realizar uma transação:

   candidates:
     - first_simple:
         variants:
           - speech: Sorry you cannot perform a digital purchase.
   

9. Em Transição, selecione Encerrar conversa para encerrar a conversa.

2. b. Coletar inventário disponível

Use a API de compras digitais para solicitar seu inventário da Play Store atualmente disponível e crie isso em uma matriz de objetos JSON para cada produto. Faça referência a essa matriz mais tarde para mostrar ao usuário quais opções estão disponíveis para compra.

Cada um dos seus produtos digitais é representado como um SKU em um formato JSON. 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 para o endpoint 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 uma matriz de objetos de SKU.

Para recuperar apenas produtos digitais específicos na matriz resultante, liste os IDs dos produtos (conforme mostrado em cada produto no app no Google Play Console) que você quer disponibilizar para compra em body.ids.

O código Node.js a seguir solicita uma lista de produtos disponíveis da API de compras digitais 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': ['annual.subscription']
      },
    }, (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 digitais disponíveis para compra. Você pode usar vários tipos de resposta avançada para representar seu estoque e solicitar que o usuário faça uma seleção.

Dica :se você tem apenas um item para vender, simplifique a interação com uma resposta simples e processe "sim" ou "não" como um acompanhamento.

O código Node.js a seguir lê uma matriz de inventário de objetos SKU e cria uma resposta de lista com um item de lista para cada um:

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 a partir da seleção do usuário

Depois que o usuário seleciona um item, você pode criar o pedido. Para fazer isso, chame o webhook no espaço associado ao item selecionado para criar o pedido. No fulfillment, salve os dados do pedido em um parâmetro de sessão. O objeto de pedido é usado em cenas para a 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, é possível usar o editor de JSON para configurar o espaço com o objeto de pedido acima. Ambas as 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 o slot associado ao item selecionado, faça a transição para uma cena que realiza uma compra completa.

Cuidado: não use o simulador do Console do Actions para testar esta etapa. Para testar o gerenciamento de compras digitais do seu Action, use o Google Assistente em um dispositivo Android com a mesma Conta do Google que o projeto do Console do Actions.

Criar cena de compra completa

1. Na guia Cenas, adicione uma nova cena com o nome CompletePurchase.
2. Em Preenchimento de slot, clique em + para adicionar um novo slot.
3. Em Selecionar tipo, selecione actions.type.CompletePurchaseValue como o tipo de slot.
4. No campo "Nome do slot", dê o nome CompletePurchase.
5. Marque a caixa de seleção Personalizar writeback do valor do slot (ativada por padrão).
6. Em Configurar slot, selecione Use session parameter no menu suspenso.
7. Em Configurar slot, insira o nome do parâmetro de sessão usado para armazenar o pedido no campo de texto (por exemplo, $session.params.purchase).
8. Clique em Salvar.

5. Lide com o resultado

Um slot com o tipo actions.type.CompletePurchaseValue pode ter os seguintes resultados:

• PURCHASE_STATUS_OK: a compra foi realizada. A transação está concluída neste momento. Portanto, saia do fluxo transacional e volte para sua conversa.
• PURCHASE_STATUS_ALREADY_OWNED: a transação falhou porque o usuário já é proprietário do item. Para evitar esse erro, verifique as compras anteriores do usuário e personalize os itens exibidos para que ele não tenha a opção de comprar novamente os itens que já são dele.
• PURCHASE_STATUS_ITEM_UNAVAILABLE: a transação falhou porque o item solicitado não está disponível. Para evitar esse erro, verifique as SKUs disponíveis próximas ao momento da compra.
• PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: a transação falhou porque o usuário decidiu comprar outra coisa. Solicitar a criação do seu pedido novamente para que o usuário possa tomar outra decisão imediatamente.
• PURCHASE_STATUS_USER_CANCELLED: a transação falhou porque o usuário cancelou o fluxo de compra. Como o usuário saiu do fluxo prematuramente, pergunte a ele se quer repetir a transação ou sair dela.
• PURCHASE_STATUS_ERROR: ocorreu uma falha na transação por um motivo desconhecido. Informe ao usuário que a transação falhou e pergunte se ele quer tentar novamente.
• PURCHASE_STATUS_UNSPECIFIED: a transação falhou por um motivo desconhecido, resultando em um status desconhecido. Para lidar com esse status de erro, informe ao usuário que a transação falhou e pergunte se ele quer tentar novamente.

Você deve gerenciar cada um desses resultados a partir da cena CompletePurchase.

1. Na guia Cenas, selecione a cena CompletePurchase recém-criada.
2. Em Condição, clique em + para adicionar uma nova condição.

3. No campo de texto, insira a seguinte sintaxe de condição para verificar a condição:

   scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
   

4. Passe o cursor sobre a condição que você acabou de adicionar e clique na seta para cima para colocá-la antes de if scene.slots.status == "FINAL".

5. Ative Enviar solicitações e forneça uma solicitação simples informando ao usuário que ele está pronto para fazer uma transação:

   candidates:
     - first_simple:
         variants:
           - speech: >-
               Your purchase was successful.
   

6. Em Transição, selecione Encerrar conversa para encerrar a conversa.

Repita as etapas acima para cada tipo de resultado de compra que você quer oferecer.

Refletir as compras do usuário

Quando um usuário consulta sua ação, o objeto user da solicitação JSON inclui uma lista de compras. Verifique essas informações e altere a resposta da ação com base no conteúdo pago pelo usuário.

Observação: a solicitação JSON inclui apenas compras feitas pelo usuário na Play Store ou na sua ação em um dispositivo Android. Para acessar as compras feitas em plataformas que não são Android, peça ao usuário para vincular as contas. É possível consultar o histórico da conta do usuário para identificar as compras feitas em outras plataformas.

O exemplo de código a seguir mostra um objeto user de uma solicitação que inclui packageEntitlements de compras no app anteriores feitas 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 o projeto

Ao testar seu projeto, é possível ativar o modo sandbox no Console do Actions para testar a ação sem cobrar uma forma de pagamento. Para ativar o modo sandbox, siga estas etapas:

1. No Console do Actions, clique em Testar na navegação.
2. Clique em Configurações.
3. Ative a opção Sandbox de desenvolvimento.