Criar transações digitais que não são de consumo (Dialogflow)

Este guia explica como adicionar transações digitais à sua ação de conversa para que os usuários possam comprar seus produtos digitais que não são de consumo.

Termos-chave: um produto digital que não é de consumo é uma unidade de manutenção de estoque (SKU) que só pode ser comprada uma vez, como acesso pago a conteúdo extra em apps Android de ação ou para Android. Esse tipo de produto é diferente de uma mercadoria digital de consumo que pode ser comprada, usada e recomprada.

Para ver mais informações sobre produtos de aquisição única que não são de consumo, consulte a documentação do Android sobre recursos específicos de produtos de aquisição única.

Restrições e diretrizes de revisão

Outras políticas se aplicam a ações com transações. Pode levar algumas semanas para analisar as ações que incluem transações. Portanto, considere esse tempo ao planejar a programação de lançamento. 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 análise.

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 análise, talvez você veja as transações realizadas por usuários desconhecidos. Esses usuários são associados ao Google como parte do processo de análise da ação das transações. A Ação não será disponibilizada ao público em geral até ser totalmente revisada e publicada.

Fluxo de transações

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

1. Configurar um cliente da API Digital Purchases: a ação usa a API Digital Purchases para se comunicar com o inventário do Google Play e fazer transações. Antes de a ação fazer qualquer outra coisa, ela cria um cliente JWT com uma chave de serviço para se comunicar com a API de compras digitais.
2. Coletar informações: a ação reúne informações básicas sobre o usuário e seu inventário do Google Play para se preparar para uma transação.
   1. Validar os requisitos de transação: a ação usa o assistente 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 seu inventário do Google Play e identifica quais itens estão disponíveis para compra no momento.
3. Criar o pedido: sua ação apresenta os produtos e softwares digitais disponíveis ao usuário para que ele possa selecionar um para comprar.
4. Concluir a compra: a ação usa a API de compras digitais para iniciar uma compra com a seleção do usuário na Google Play Store.
5. Processar o resultado: a ação recebe um código de status para a transação e notifica o usuário de que a compra foi concluída ou exige outras etapas.

Pré-requisitos

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

• 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 que seja 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 serão "compras no app" associadas a este app no Google Play Console.

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

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

• Um ou mais produtos gerenciados no Google Play Console, que são os produtos e softwares digitais que você vende com sua Ação. Só é possível criar produtos gerenciados no Play Console depois que você configurar 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 tiver um app Android com permissão de faturamento no Google Play Console, siga estas etapas:

1. No Android Studio ou no ambiente de desenvolvimento integrado do Android de sua escolha, crie um novo projeto. Escolha as opções nas solicitações de configuração do projeto para criar um app muito básico.
2. 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 fazer upload de pacotes que incluem 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 e Generate Signed Bundle / APK.
   2. Clique em Next.
   3. Em Caminho do repositório de chaves, clique em Criar novo.
   4. Preencha todos os campos e clique em OK. Anote a senha do keystore e a senha da chave e armazene-as em um local seguro para usar mais tarde.
   5. Clique em Next.
   6. Selecione release.
   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 clique em Alfa.

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

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

11. Faça upload do arquivo APK.

12. Clique em Salvar.

Crie seus produtos digitais

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

1. No Google Play Console, acesse Produtos no app e depois Produtos gerenciados. Se um aviso aparecer, siga as instruções anteriores para criar um app Android ou clique no link para criar um perfil de comerciante.
2. Clique em Criar um produto gerenciado.
3. Preencha os campos do produto digital. Anote o ID do produto, que é como você vai referenciar 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

Com seus produtos e softwares digitais configurados no Google Play Console, você precisa ativar transações digitais e associar seu projeto do Actions ao app do Google Play.

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 Digital Purchase para realizar transações de produtos e softwares 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, faça o download de uma chave de conta de serviço JSON associada ao seu projeto do Console do Actions.

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 Configurações do projeto.
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 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 essa chave da conta de serviço em um local seguro. Você usará essa chave no fulfillment para criar um cliente para a API Digital Purchases.

Conectar ao inventário do Google Play

Para acessar seus produtos e softwares digitais em 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 domínio da Web e o app do Play Console ao projeto do Actions, siga estas etapas:

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

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

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

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

3. Depois de ter pelo menos um site conectado, siga estas etapas para conectar seu app Android:

   1. No Console do Actions, acesse Implantar e depois Verificação de 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 e softwares digitais e insira o URL do domínio da Web exatamente como aparece na página Verificação de marca.

      Mais uma vez, o Google envia um e-mail de verificação para o proprietário verificado do domínio. Depois que ele aprovar a verificação, seu app do Google Play aparecerá em Verificação de marca.

      Observação: o domínio da Web vai 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 a opção Acessar compras no Google Play.

Crie seu fluxo de compra

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

1. Configurar um cliente da API Digital Purchases

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 :encontre etapas de instalação mais detalhadas e exemplos na página do GitHub da biblioteca de cliente da API do Google.

2. Coletar informações

Antes 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 da transação

É recomendável verificar se a conta do usuário está configurada para realizar transações antes de oferecer a opção de fazer uma compra. Essa etapa inclui verificar se o usuário tem uma forma de pagamento configurada e se ele está em uma localidade com suporte a transações digitais. No início do fluxo de transações, use o auxiliar DIGITAL_PURCHASE_CHECK para validar a configuração da transação do usuário com o Google Assistente.

O código Node.js a seguir usa o DIGITAL_PURCHASE_CHECK no início da conversa:

app.intent('Default Welcome Intent', async (conv, { SKU }) => {
  // Immediately invoke digital purchase check intent to confirm
  // purchase eligibility.
  conv.ask(new DigitalPurchaseCheck());
});

Encontre o resultado dessa verificação nos argumentos da conversa como DIGITAL_PURCHASE_CHECK_RESULT. Com base nesse resultado, continue o fluxo de transação ou afaste-se e solicite que eles verifiquem a configuração do Google Pay.

O código Node.js a seguir processa o resultado da verificação de requisitos :

app.intent('Digital Purchase Check', async (conv) => {
  const arg = conv.arguments.get('DIGITAL_PURCHASE_CHECK_RESULT');
  if (!arg || !arg.resultType) {
    conv.close('Digital Purchase check failed. Please check logs.');
    return;
  }
  // User does not meet necessary conditions for completing a digital purchase
  if (arg.resultType === 'CANNOT_PURCHASE' || arg.resultType === 'RESULT_TYPE_UNSPECIFIED') {
    conv.close(`It looks like you aren't able to make digital purchases. Please check your Google Pay configuration and try again.`);
    return;
  }
  conv.ask('Welcome to the Digital Goods Sample. Would you like to see what I have for sale?');
});

2. b) Reunir inventário disponível

Use a API Digital Purchases para solicitar seu inventário da Play Store disponível no momento e crie-o em uma matriz de objetos JSON para cada produto. Você vai consultar essa matriz mais tarde para mostrar ao usuário quais opções estão disponíveis para compra.

Cada um dos seus produtos e softwares digitais é representado como uma SKU no formato JSON. O código Node.js a seguir descreve a formatação esperada de cada SKU:

body = {
  skus: [
    skuId: {
      skuType: one of "APP" or "UNSPECIFIED"
      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 SKU.

Para recuperar apenas produtos e softwares digitais específicos na matriz resultante, liste os IDs de produtos para produtos e softwares digitais (conforme mostrado abaixo de 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': conversationId,
        'skuType': 'APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['nonconsumable.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. É possível usar uma variedade de tipos de resposta avançada para representar sua 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 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:

skus.forEach((sku) => {
  const key = `${sku.skuId.skuType},${sku.skuId.id}`
  list.items[key] = {
    title: sku.title,
    description: `${sku.description} | ${sku.formattedPrice}`,
  };
});

4. Concluir a compra

Para concluir a compra, use a intent auxiliar COMPLETE_PURCHASE com o item que o usuário selecionou.

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

O código Node.js a seguir processa a seleção de SKU do usuário com base em uma resposta de lista e solicita a intent COMPLETE_PURCHASE com essas informações:

app.intent('Send Purchase', (conv, params, option) => {
  let [skuType, id] = option.split(',');

  conv.ask(new CompletePurchase({
    skuId: {
      skuType: skuType,
      id: id,
      packageName: <PACKAGE_NAME>,
    },
  }));
});

5. Processar o resultado

Quando a compra é concluída, ela aciona o evento actions_intent_COMPLETE_PURCHASE do Dialogflow (ou a intent do SDK das Ações actions.intent.COMPLETE_PURCHASE) com um argumento COMPLETE_PURCHASE_VALUE que descreve o resultado. Crie uma intent, acionada por esse evento, que comunique o resultado ao usuário.

Processe os seguintes resultados de compra possíveis:

• PURCHASE_STATUS_OK: a compra foi concluída. A transação está concluída neste ponto, então saia do fluxo transacional e volte para sua conversa.
• PURCHASE_STATUS_ALREADY_OWNED: a transação falhou porque o usuário já é o proprietário desse item. Para evitar esse erro, verifique as compras anteriores do usuário e adapte os itens mostrados para que ele não tenha a opção de comprar itens que já pertencem a ele.
• PURCHASE_STATUS_ITEM_UNAVAILABLE: a transação falhou porque o item solicitado não está disponível. Para evitar esse erro, consulte as SKUs disponíveis mais perto do momento da compra.
• PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: a transação falhou porque o usuário decidiu comprar outra coisa. Crie o 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 se ele quer tentar novamente ou sair da transação.
• 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 novamente.
• PURCHASE_STATUS_UNSPECIFIED: a transação falhou por um motivo desconhecido, resultando em um status desconhecido. Gerencie esse status de erro informando ao usuário que a transação falhou e pergunte se ele quer tentar novamente.

O código Node.js a seguir lê o argumento COMPLETE_PURCHASE_VALUE e processa cada resultado:

app.intent('Purchase Result', (conv) => {
  const arg = conv.arguments.get('COMPLETE_PURCHASE_VALUE');
  console.log('User Decision: ' + JSON.stringify(arg));
  if (!arg || !arg.purchaseStatus) {
    conv.close('Purchase failed. Please check logs.');
    return;
  }
  if (arg.purchaseStatus === 'PURCHASE_STATUS_OK') {
    conv.close(`Purchase completed! You're all set!`);
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ALREADY_OWNED') {
    conv.close('Purchase failed. You already own this item.');
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_UNAVAILABLE') {
    conv.close('Purchase failed. Item is not available.');
  } else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_CHANGE_REQUESTED') {
    // Reprompt with your item selection dialog
  }  else {
    conv.close('Purchase Failed:' + arg.purchaseStatus);
  }
});

Refletem as compras do usuário.

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

Observação: o JSON de solicitação inclui apenas compras que o usuário fez na Play Store ou na sua ação em um dispositivo Android. Para acessar 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 que ele fez em outras plataformas.

O exemplo de código a seguir mostra o objeto user de uma solicitação que inclui packageEntitlements de compras no app anteriores feitas para o pacote com.digitalgoods.application:

  "user": {
    "userId": "xxxx",
    "locale": "en-US",
    "lastSeen": "2018-02-09T01:49:23Z",
    "packageEntitlements": [
      {
        "packageName": "com.digitalgoods.application",
        "entitlements": [
          {
            "sku": "non-consumable.1",
            "skuType": "APP"
          }
          {
            "sku": "consumable.2",
            "skuType": "APP"
          }
        ]
      },
      {
        "packageName": "com.digitalgoods.application",
        "entitlements": [
          {
            "sku": "annual.subscription",
            "skuType": "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=="
            }
          }
        ]
      }
    ]
  },
  "conversation": {
    "conversationId": "1518141160297",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to My Test App"
        }
      ]
    }
  ],
  ...
}