Sobre este codelab
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 do 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
É possível usar cartões genéricos para qualquer caso de uso que possa ser apresentado com:
- Até três linhas de informações
- (Opcional) Gráfico de código de barras
- Seção de detalhes (opcional)
Para mais informações sobre a API Google Wallet ou como adicionar um botão Adicionar à Carteira do Google a um app Android, consulte a documentação para desenvolvedores da Carteira do Google.
Classes e objetos de cartão
A API Google Wallet expõe métodos para criar o seguinte:
Tipo | Descrição |
Classe do cartão | Um modelo para um objeto de cartão individual. Ele contém informações comuns a todos os objetos de cartão que pertencem a essa classe. |
Objeto de cartão | Uma instância de uma classe de cartão exclusiva para um ID do usuário. |
Sobre este codelab
Neste codelab, você vai concluir as seguintes tarefas.
- Criar uma nova conta de emissor no modo de demonstração
- Criar uma conta de serviço para emitir cartões
- Criar uma nova classe de cartão genérico
- Criar um novo objeto de cartão
- Crie um botão Adicionar à Carteira do Google para salvar um cartão
- Mostrar o botão no app Android
- Processar o resultado da gravação do 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
Depois de concluir este codelab, você vai conseguir fazer o seguinte:
- Adicionar o SDK da Carteira do Google ao 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ê ficar preso em algum ponto do codelab, o repositório do GitHub google-pay/wallet-android-codelab (link em inglês) 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, você pode criar classes e objetos de cartão que podem ser adicionados às carteiras dos usuários. Em seguida, você vai criar um projeto e uma conta de serviço do Google Cloud. Elas serão usadas para criar classes e objetos de cartão de maneira programática da mesma forma que um servidor de back-end. Por fim, você vai autorizar a conta de serviço do Google Cloud a gerenciar cartões na sua conta de emissor da Carteira do Google.
Criar uma conta de emissor da API Google Wallet
É necessário ter uma conta de emissor para criar e distribuir cartões da Carteira do Google. Você pode se inscrever usando o Console do Google Pay e 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 poderão adicionar os cartões que você criar. Os usuários de teste podem ser gerenciados no Console do Google Pay e da Carteira.
Para mais informações sobre o modo de demonstração, consulte os Pré-requisitos de cartão genérico.
- Abra o Console do Google Pay e da Carteira.
- Siga as instruções na tela para criar uma conta de emissor.
- Selecione a API Google Wallet.
- Confirme que você entendeu os Termos de Serviço e a Política de Privacidade
- Copie o valor do ID do emissor para um editor de texto ou outro local.
- Na guia Gerenciar, selecione Configurar contas de teste.
- Adicione os endereços de e-mail que você vai usar neste codelab
Ativar a API Google Wallet
- Faça login no console do Google Cloud.
- Se você ainda não tiver um projeto do Google Cloud, crie um agora. Consulte Criar e gerenciar projetos para mais informações.
- Ative a API Google Wallet (também chamada de API Google Pay for Passes) para seu projeto.
Crie uma conta de serviço e uma chave
Uma conta de serviço e uma chave de 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. Essa chave é sensível, portanto, mantenha-a em segredo.
Criar uma conta de serviço
- No console do Google Cloud, abra Contas de serviço.
- Insira um nome, um ID e uma descrição para sua conta de serviço
- Selecione CRIAR E CONTINUAR.
- Selecione CONCLUÍDO.
Criar uma chave de conta de serviço
- Selecione sua conta de serviço
- Selecione o menu KEYS.
- Selecione ADICIONAR CHAVE e Criar nova chave.
- Selecione o tipo de chave JSON
- Selecione CRIAR.
Você vai receber uma solicitação para salvar o arquivo de chave na estação de trabalho local. Não se esqueça de onde ele está.
Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
.
A variável de ambiente GOOGLE_APPLICATION_CREDENTIALS
é usada pelos SDKs do Google para autenticar como uma conta de serviço e acessar diferentes APIs em um projeto do Google Cloud.
- Siga as instruções na documentação sobre chaves de conta de serviço do Google Cloud para definir a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
. - Verifique se a variável de ambiente está definida em uma nova sessão de terminal (MacOS/Linux) ou 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.
- Abra o Console do Google Pay e da Carteira.
- Selecione Usuários.
- Selecione Convidar um usuário.
- Insira o endereço de e-mail da conta de serviço (por exemplo,
test-svc@myproject.iam.gserviceaccount.com
). - Selecione Desenvolvedor ou Administrador no menu suspenso Nível de acesso.
- Selecione Convidar.
3. Criar uma classe de cartão genérico
Nesta etapa, você vai criar a classe base do seu cartão. Sempre que um novo cartão for criado para um usuário, ele vai herdar as propriedades definidas na classe do cartão.
A classe de cartão que você vai criar durante este 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 a partir dessa classe, ele fica parecido com o gráfico a seguir.
As classes de cartão podem ser criadas diretamente no Console do Google Pay e 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.
- 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
- Abra o repositório clonado no terminal ou no prompt de comando.
- Navegue até o diretório
backend
(esses scripts imitam ações do servidor de back-end)cd backend
- Instale as dependências do Node.js:
npm install .
- No diretório
backend
, abrageneric_class.js
. - Substitua o valor de
issuerId
pelo seu ID do emissor no Console do Google Pay e da Carteira.// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - No terminal ou no prompt de linha de comando, execute o script
generic_class.js
.node generic_class.js
Quando o código for executado, ele vai criar uma nova classe de cartão e gerar o ID da classe. O ID da classe é composto pelo ID do emissor seguido de um sufixo definido pelo desenvolvedor. Nesse caso, o sufixo é definido como codelab_class
(o ID da classe é semelhante a 1234123412341234123.codelab_class
). Os registros de saída também vão incluir 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 esta atividade para incluir um botão Adicionar à Carteira do Google em uma página de produto.
- Abrir o Android Studio
- Selecione Arquivo e Abrir.
- Selecione o diretório
android
no repositório. - Selecione Abrir.
Adicionar o SDK da Carteira do Google ao app
- Abra o arquivo de build do Gradle no nível do módulo (
android/app/build.gradle
). - Adicionar 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" - Salve o arquivo
- Selecione File e Sync Project with Gradle Files.
5. Criar 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. Os recursos do botão já foram incluídos no projeto. Para incluir o botão, você vai criar um arquivo de layout separado. Depois de adicionado, o botão vai ficar assim:
- Crie um novo arquivo de layout:
app/src/main/res/layout/add_to_google_wallet_button.xml
- 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> - 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 seu app em um dispositivo que não oferece suporte à API Google Wallet, a experiência de adicionar o cartão pode ser 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 evita possíveis confusões. Há vários motivos para a API não estar disponível. As versões do Android ou do Google Play Services podem estar desatualizadas ou a Carteira do Google pode não estar disponível no país do usuário.
Nesta etapa, você vai adicionar uma lógica ao app que verifica 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 será ocultado.
- Abrir o arquivo
CheckoutActivity.kt
noapp/src/main/java/com/google/android/gms/samples/wallet/activity/
- Criar 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 - Crie uma instância da propriedade
PayClient
no métodoonCreate
.// TODO: Instantiate the client
walletClient = Pay.getClient(this) - Criar um método que verifique se o SDK e a API da Carteira do Google 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
}
} - Chame o método
fetchCanUseGoogleWalletApi
no métodoonCreate
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.
7. Criar um objeto de cartão genérico
Agora que você confirmou que a API Google Wallet está disponível, crie um cartão e peça para o usuário adicioná-lo à carteira. Há dois fluxos para criar objetos de cartão para 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. Essa opção é mais adequada para casos em que a adoção do usuário é alta, porque garante que o objeto exista antes que o usuário tente adicioná-lo à carteira.
Criar o objeto de cartão quando o usuário o adicionar à carteira
Nessa abordagem, o objeto de cartão é definido e codificado em um JWT assinado no servidor de back-end. Um botão Adicionar à Carteira do Google é renderizado no app cliente que faz referência ao JWT. Quando o usuário seleciona o botão, o JWT é usado para criar o objeto de cartão. Esse método é mais adequado para casos em que a adoção do usuário é variável ou desconhecida, porque ele impede que os objetos de cartão sejam criados e não usados. Essa abordagem será usada no codelab.
- Abra o arquivo
backend/generic_pass.js
. - Substitua o valor de
issuerId
pelo seu ID do emissor no Console do Google Pay e da Carteira.// TODO: Define Issuer ID
let issuerId = 'ISSUER_ID'; - No terminal ou no prompt de linha de comando, execute o arquivo
generic_pass.js
.node generic_pass.js
- Copie o token de saída para a área de transferência ou um editor de texto
Quando o código for executado, ele vai definir um novo objeto de cartão e incorporá-lo a um JWT. O JWT é assinado pela chave da conta de serviço que você criou 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, o sistema de back-end é responsável por criar JWTs e os retornar aos clientes. Neste codelab, o script generic_pass.js
emula esse comportamento e "retorna" um token para você usar no app 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, pode pedir que o usuário adicione o cartão à carteira. 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.
- Abra o arquivo
app/src/main/CheckoutActivity.kt
. - Substitua o valor de
token
pelo JWT que você criou anteriormente.// TODO: Save the JWT from the backend "response"
private val token = "TOKEN" - Criar uma propriedade de classe para armazenar o código da solicitação
// TODO: Add a request code for the save operation
private val addToGoogleWalletRequestCode = 1000 - 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. Esse método solicita que o usuário adicione o novo objeto de cartão à Carteira do Google.
9. Processar o resultado do savePassesJwt
Na etapa final deste codelab, você vai configurar o app para processar o resultado da operação walletClient.savePassesJwt
.
- Abra o arquivo
app/src/main/CheckoutActivity.kt
. - Substitua o método
onActivityResult
para conter o seguinte 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 o app pode lidar com os seguintes cenários:
- Adição de cartão bem-sucedida
- Cancelamento do usuário
- Erros inesperados
Execute o app para confirmar se você pode adicionar o cartão e processar o resultado como esperado.
10. Parabéns
Parabéns! Você integrou a API Google Wallet ao Android.
Saiba mais
Confira a integração completa no repositório do GitHub google-pay/wallet-android-codelab.
Criar cartões e solicitar acesso de produção
Quando quiser emitir seus próprios cartões durante a produção, acesse o Console da Carteira do Google e do Google Pay para solicitar o acesso de produção e autorizar seu app Android.
Consulte os Pré-requisitos do SDK do Android para saber mais.