Criar cartões no Android usando a API Google Wallet

1. Introdução

Visão geral

A API Google Wallet permite interagir com usuários usando vários tipos de cartões: cartões de fidelidade, ofertas, vales-presente, ingressos de eventos, bilhetes de transporte público, cartões de embarque e muito mais. Cada tipo de cartão, ou classe de cartão, vem com campos e recursos específicos ao caso de uso para melhorar a experiência do usuário.

No entanto, eles podem não se adequar a todos os casos de uso. Para criar uma experiência mais personalizada, use o tipo de cartão genérico. Veja alguns exemplos de casos de uso para o tipo de cartão genérico:

• Bilhetes de estacionamento
• Cartões de inscrição em bibliotecas
• Cupons de valor armazenado
• Cartões de inscrição em academias
• Reservas

Você pode usar cartões genéricos para qualquer caso de uso que possa ser apresentado:

• Até três linhas de informações
• (Opcional) Gráfico de código de barras
• (Opcional) Seção "Detalhes"

Para mais informações sobre a API Google Wallet ou sobre como adicionar um botão Adicionar à Carteira do Google a um app Android, consulte a documentação do desenvolvedor da Carteira do Google.

Todas as classes e objetos de cartão precisam aderir à Política de Uso Aceitável.

Classes e objetos de cartão

A API Google Wallet apresenta métodos para criar o seguinte:

Tipo	Descrição
Classe de cartão	Um modelo para um objeto de cartão individual. Ela contém informações comuns a todos os objetos de cartão que pertencem a essa classe.
Objeto do cartão	Uma instância de uma classe de cartão exclusiva para um ID de usuário.

Sobre este codelab

Neste codelab, você concluirá as tarefas a seguir.

1. Criar uma nova conta de emissor no modo de demonstração
2. Criar uma conta de serviço para emitir cartões
3. Criar uma nova classe de cartão genérico
4. Criar um novo objeto de cartão
5. Criar um botão Adicionar à Carteira do Google para salvar um cartão
6. Exibir o botão no seu app Android
7. Processar o resultado do salvamento de cartão

Pré-requisitos

• Android Studio
• Git
• Uma Conta do Google com acesso ao console do Google Cloud
• Node.js versão 10 ou mais recente

Objetivos

Após concluir este codelab, você vai conseguir fazer o seguinte:

• Adicionar o SDK da Carteira do Google ao seu app Android
• Verificar se a API Google Wallet está disponível em um dispositivo Android
• Criar um botão Adicionar à Carteira do Google

Suporte

Se você não souber o que fazer no codelab, o repositório google-pay/wallet-android-codelab do GitHub contém uma solução completa para referência.

2. Configuração

Nesta etapa, você vai criar uma conta de emissor no modo de demonstração. Assim, será possível criar classes e objetos de cartão que podem ser adicionados às carteiras dos usuários. Em seguida, crie um projeto e uma conta de serviço do Google Cloud. Eles serão usados para criar classes e objetos de cartão de forma programática da mesma maneira que um servidor de back-end. Por fim, você autorizará a conta de serviço do Google Cloud a gerenciar cartões na sua conta do emissor da Carteira do Google.

É possível criar classes e objetos de cartão em clientes públicos, como aplicativos para dispositivos móveis. No entanto, é mais seguro criar cartões em um cliente particular, como um servidor de back-end, ou buscá-los em seus aplicativos clientes por meio de solicitações autenticadas e seguras.

Criar uma conta de emissor da API Google Wallet

É necessário ter uma conta de emissor para criar e distribuir cartões para a Carteira do Google. Você pode se inscrever usando o Google Pay e Console da Carteira. Inicialmente, você terá acesso para criar cartões no modo de demonstração. Isso significa que apenas usuários de teste específicos vão poder adicionar os cartões criados por você. Os usuários de teste podem ser gerenciados no Google Pay e Console da Carteira.

Para mais informações sobre o modo de demonstração, consulte os Pré-requisitos do cartão genéricos.

1. Abra a página do Google Pay e Console da Carteira
2. Siga as instruções na tela para criar uma conta de emissor
3. Selecione API Google Wallet.
4. Confirme que você entende os Termos de Serviço e a Política de Privacidade
5. Copie o valor de Código do emissor em um editor de texto ou outro local.
6. Na guia Gerenciar, selecione Configurar contas de teste.
7. Adicione os endereços de e-mail que você vai usar neste codelab

Ativar a API Google Wallet

1. Faça login no console do Google Cloud.
2. Se você ainda não tiver um projeto do Google Cloud, crie um agora. Consulte Como criar e gerenciar projetos para mais informações.
3. Ative a API Google Wallet (também conhecida como API Google Pay for Passes) no projeto.

Crie uma conta de serviço e uma chave

Uma conta de serviço e uma chave da conta de serviço são necessárias para chamar a API Google Wallet. A conta de serviço é a identidade que chama a API Google Wallet. A chave da conta de serviço contém uma chave privada que identifica seu aplicativo como a conta de serviço. Como essa chave é confidencial, ela precisa ser mantida em sigilo.

Tenha cuidado ao usar uma conta de serviço já existente para este codelab, porque ela pode ter permissões para outros recursos que não são necessários.

Criar uma conta de serviço

1. No console do Google Cloud, abra Contas de serviço
2. Digite um nome, um ID e uma descrição para a conta de serviço
3. Selecione CRIAR E CONTINUAR.
4. Selecione CONCLUÍDO.

Criar uma chave de conta de serviço

1. Selecione sua conta de serviço
2. Selecione o menu KEYS.
3. Selecione ADICIONAR CHAVE e escolha Criar chave
4. Selecione o tipo de chave JSON.
5. Selecione CRIAR.

Será solicitado que você salve o arquivo de chave na estação de trabalho local. Não se esqueça da localização dele.

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

A variável de ambiente GOOGLE_APPLICATION_CREDENTIALS é usada pelos SDKs do Google para fazer a autenticação como uma conta de serviço e acessar diferentes APIs em um projeto do Google Cloud.

1. Siga as instruções na documentação das chaves de conta de serviço do Google Cloud para definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
2. Verifique se a variável de ambiente está definida em um novo terminal (MacOS/Linux) ou sessão de linha de comando (Windows). Talvez seja necessário iniciar uma nova sessão se você já tiver uma aberta.

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autorizar a conta de serviço

Por fim, você precisa autorizar a conta de serviço a gerenciar os cartões da Carteira do Google.

1. Abra a página do Google Pay e Console da Carteira
2. Selecione Usuários.
3. Selecione Convidar um usuário.
4. Insira o endereço de e-mail da conta de serviço (por exemplo, [e-mail])
5. Selecione Desenvolvedor ou Administrador no menu suspenso Nível de acesso.
6. Selecione Convidar.

3. Criar uma classe de cartão genérico

Nesta etapa, você criará a classe de base do cartão. Sempre que um novo cartão é criado para um usuário, ele herda as propriedades definidas na classe de cartão.

A classe de cartão que você vai criar neste codelab usa a flexibilidade dos cartões genéricos para criar um objeto que funciona como um selo de identidade e um rastreador de pontos de desafio. Quando um objeto de cartão é criado com base nessa classe, ele se parece com o gráfico a seguir.

Este gráfico ilustra um pequeno subconjunto de propriedades que podem ser definidas em um cartão. Consulte o modelo de cartão genérico para saber como diferentes propriedades afetam a experiência do usuário.

As classes de cartão podem ser criadas diretamente na página do Google Pay e Console da Carteira ou usando a API Google Wallet. Neste codelab, você vai criar a classe de cartão genérico usando a API. Isso segue o processo que um servidor de back-end privado usaria para criar classes de cartão.

1. Clone o repositório do GitHub google-pay/wallet-android-codelab na sua estação de trabalho local

   git clone https://github.com/google-pay/wallet-android-codelab.git
   

2. Abra o repositório clonado no seu terminal ou prompt de linha de comando.
3. Navegue até o diretório backend (esses scripts imitam as ações do servidor de back-end).

   cd backend
   

4. Instale as dependências do Node.js

   npm install .
   

5. No diretório backend, abra generic_class.js
6. Substitua o valor de issuerId pelo seu ID de emissor do Google Pay e Console da Carteira

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

7. No terminal ou no prompt de linha de comando, execute o script generic_class.js

   node generic_class.js
   

Quando seu código é executado, ele cria uma nova classe de cartão e gera o ID da classe. O ID da classe é composto pelo ID do emissor seguido por um sufixo definido pelo desenvolvedor. Nesse caso, o sufixo está definido como codelab_class (o ID da classe seria semelhante a 1234123412341234123.codelab_class). Os registros de saída também incluem a resposta da API Google Wallet.

4. Abrir o projeto no Android Studio

O repositório do GitHub que você clonou contém um projeto Android com uma atividade vazia. Nesta etapa, você vai editar essa atividade para incluir um botão Adicionar à Carteira do Google em uma página de produto.

1. Abrir o Android Studio
2. Selecione Arquivo e depois Abrir.
3. Selecione o diretório android no repositório
4. Selecione Abrir.

Adicionar o SDK da Carteira do Google ao seu app

1. Abra o arquivo de build do Gradle no nível do módulo (android/app/build.gradle).
2. Adicione o SDK da Carteira do Google à seção dependencies

   // TODO: Add the "com.google.android.gms:play-services-pay" dependency to
   //       use the Google Wallet API
   implementation "com.google.android.gms:play-services-pay:16.0.3"
   

3. Salve o arquivo
4. Selecione File e Sync Project with Gradle Files.

5. Crie o Botão "Adicionar à Carteira do Google"

Nesta etapa, você vai criar um botão Adicionar à Carteira do Google e adicioná-lo a uma atividade atual. Os recursos do botão já foram incluídos no projeto. Para incluir o botão, crie um arquivo de layout separado. Depois de adicionado, o botão ficará assim.

Se você estiver adicionando o botão ao seu próprio aplicativo, acesse as diretrizes da promoção de marca para fazer o download dos arquivos SVG do botão com os idiomas que atendem às suas necessidades. Inclua apenas gráficos para as configurações compatíveis. Você pode importar recursos vetoriais no Android Studio em File > Novo > Vector Asset. Selecione Local file no assistente, insira um nome (por exemplo, add_to_google_wallet_button) e localize o arquivo em sua estação de trabalho.

1. Criar um novo arquivo de layout: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Adicione o seguinte conteúdo ao novo arquivo de layout

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="48sp"
       android:background="@drawable/add_to_google_wallet_button_background_shape"
       android:clickable="true"
       android:contentDescription="@string/add_to_google_wallet_button_content_description"
       android:focusable="true">
     <ImageView
         android:layout_width="227dp"
         android:layout_height="26dp"
         android:layout_gravity="center"
         android:duplicateParentState="true"
         android:src="@drawable/add_to_google_wallet_button_foreground" />
   </FrameLayout>
   

3. Incluir o layout add_to_google_wallet_button.xml no arquivo de layout da atividade de finalização de compra (app/src/main/res/layout/activity_checkout.xml)

   <!--
       TODO: Create the button under `add_to_google_wallet_button.xml`
             and include it in your UI
   -->
   <include
       android:id="@+id/addToGoogleWalletButton"
       layout="@layout/add_to_google_wallet_button"
       android:layout_width="match_parent"
       android:layout_height="48dp"
       android:layout_marginTop="10dp" />
   

6. Verificar se a API Google Wallet está disponível

Se um usuário abrir o app em um dispositivo que não é compatível com a API Google Wallet, a tentativa de adicionar o cartão poderá causar uma experiência negativa. Se o dispositivo do usuário não for compatível com a API Google Wallet, ocultar o botão Adicionar à Carteira do Google poderá evitar confusão. Há vários motivos para a API não estar disponível, por exemplo, quando as versões do Android ou do Google Play Services estão desatualizadas ou a Carteira do Google não está disponível no país do usuário.

Nesta etapa, você vai adicionar uma lógica ao app para verificar se a API Google Wallet está disponível no dispositivo. Nesse caso, o botão será renderizado na atividade. Caso contrário, o botão ficará oculto.

Considere usar a lógica de negócios específica do domínio de maneira adequada se estiver usando outros padrões de design. Por exemplo, se você estiver usando o padrão Model-View-ViewModel (MVVM), coloque a lógica de negócios relacionada à IU na sua atividade ou fragmento (por exemplo: elementos de interface e resultados de atividades) e lógica operacional no ViewModel (por exemplo, gatilhos de instanciação do cliente e de chamadas de rede).

1. Abrir o arquivo CheckoutActivity.kt no app/src/main/java/com/google/android/gms/samples/wallet/activity/
2. Crie uma propriedade de classe para a instância PayClient

   // TODO: Create a client to interact with the Google Wallet API
   private lateinit var walletClient: PayClient
   

3. Instancie a propriedade PayClient no método onCreate

   // TODO: Instantiate the client
   walletClient = Pay.getClient(this)
   

   .
4. Crie um método que verifique se o SDK e a API Google Wallet estão disponíveis no dispositivo e processe o resultado

   // TODO: Create a method to check for the Google Wallet SDK and API
   private fun fetchCanUseGoogleWalletApi() {
     walletClient
       .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
       .addOnSuccessListener { status ->
         if (status == PayApiAvailabilityStatus.AVAILABLE)
           layout.passContainer.visibility = View.VISIBLE
       }
       .addOnFailureListener {
         // Hide the button and optionally show an error message
       }
   }
   

5. Chame o método fetchCanUseGoogleWalletApi no método onCreate para verificar se a API Google Wallet está disponível.

   // TODO: Check if the Google Wallet API is available
   fetchCanUseGoogleWalletApi()
   

Ao executar o app, o botão Adicionar à Carteira do Google vai aparecer na interface.

Se o botão Adicionar à Carteira do Google não aparecer, verifique o erro retornado pelo método getPayApiAvailabilityStatus e os registros para saber mais. O usuário em questão pode se qualificar para usar a API no futuro.

7. Criar um objeto de cartão genérico

Se a conta do emissor estiver no modo de demonstração, você só poderá emitir cartões para seus usuários de teste. Se você executar o app usando um endereço de e-mail diferente, não será possível adicionar o cartão à sua carteira.

Agora que você confirmou que a API Google Wallet está disponível, é possível criar um cartão e solicitar que o usuário o adicione à carteira dele. Existem dois fluxos para criar objetos de cartão para os usuários.

Criar o objeto de cartão no servidor de back-end

Nessa abordagem, o objeto de cartão é criado em um servidor de back-end e retornado ao app cliente como um JWT assinado. Isso é mais adequado para casos em que a adoção pelo usuário é alta, porque garante que o objeto exista antes de o usuário tentar adicioná-lo à carteira.

Criar o objeto do cartão quando o usuário o adiciona à carteira

Nessa abordagem, o objeto de cartão é definido e codificado como um JWT assinado no servidor de back-end. Um botão Adicionar à Carteira do Google é renderizado no app cliente que referencia o JWT. Quando o usuário seleciona o botão, o JWT é usado para criar o objeto de cartão. Isso é mais adequado para casos em que a adoção pelo usuário é variável ou desconhecida, porque impede que objetos de cartão sejam criados e não usados. Essa abordagem será usada no codelab.

1. Abra o arquivo backend/generic_pass.js.
2. Substitua o valor de issuerId pelo seu ID de emissor do Google Pay e Console da Carteira

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

3. No terminal ou no prompt de linha de comando, execute o arquivo generic_pass.js

   node generic_pass.js
   

4. Copie o token de saída para a área de transferência ou um editor de texto

Quando seu código for executado, ele vai definir um novo objeto de cartão e incorporá-lo a um JWT. Em seguida, o JWT é assinado pela chave da conta de serviço criada anteriormente. Isso autentica a solicitação para a API Google Wallet para que as credenciais não precisem ser armazenadas no app cliente.

Em um ambiente de produção, seu sistema de back-end seria responsável por criar JWTs e retorná-los aos clientes. Neste codelab, o script generic_pass.js emula esse comportamento e "retorna" um token para você usar no aplicativo cliente.

8. Adicionar o cartão à Carteira do Google

Agora que você verificou que a API Google Wallet está disponível e criou um JWT assinado, solicite que o usuário adicione o cartão à carteira dele. Nesta etapa, você vai adicionar um listener ao botão Adicionar à Carteira do Google, que usa a API Google Wallet para salvar o cartão na carteira do usuário.

1. Abra o arquivo app/src/main/CheckoutActivity.kt.
2. Substitua o valor de token pelo JWT criado anteriormente

   // TODO: Save the JWT from the backend "response"
   private val token = "TOKEN"
   

3. Criar uma propriedade de classe para armazenar o código de solicitação

   // TODO: Add a request code for the save operation
   private val addToGoogleWalletRequestCode = 1000
   

4. Defina um listener para o botão Adicionar à Carteira do Google

   // TODO: Set an on-click listener on the "Add to Google Wallet" button
   addToGoogleWalletButton = layout.addToGoogleWalletButton.
   
   addToGoogleWalletButton.setOnClickListener {
     walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
   }
   

Quando um usuário seleciona o botão Adicionar à Carteira do Google, o método walletClient.savePassesJwt é chamado. Nesse método, o usuário precisa adicionar o novo objeto do cartão à Carteira do Google.

9. Lide com o Resultado de savePassesJwt

Na etapa final deste codelab, você vai configurar o app para processar o resultado da operação walletClient.savePassesJwt.

1. Abra o arquivo app/src/main/CheckoutActivity.kt.
2. Substitua o método onActivityResult para conter este código:

   // TODO: Handle the result
   override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
     super.onActivityResult(requestCode, resultCode, data)
   
     if (requestCode == addToGoogleWalletRequestCode) {
       when (resultCode) {
         RESULT_OK -> {
           // Pass saved successfully. Consider informing the user.
         }
   
         RESULT_CANCELED -> {
           // Save canceled
         }
   
         PayClient.SavePassesResult.SAVE_ERROR ->
           data?.let { intentData ->
             val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
             // Handle error. Consider informing the user.
             Log.e("SavePassesResult", errorMessage.toString())
           }
   
         else -> {
           // Handle unexpected (non-API) exception
         }
       }
     }
   }
   

Agora, seu app é capaz de lidar com os seguintes cenários:

• O cartão foi adicionado com sucesso
• Cancelamento do usuário
• Erros inesperados

Execute o app para confirmar se você pode adicionar o cartão e processar o resultado conforme esperado.

10. Parabéns

Parabéns! Você integrou a API Google Wallet no Android.

Saiba mais

Confira a integração completa no repositório google-pay/wallet-android-codelab do GitHub.

Criar cartões e solicitar acesso de produção

Quando estiver tudo pronto para emitir seus próprios cartões em produção, acesse a página do Google Pay e Console da Carteira para solicitar acesso de produção e autorizar seu app Android.

Consulte os Pré-requisitos do SDK do Android para saber mais.