Integrar a API Google Wallet para digitalizar cartões no Android

1. Antes de começar

A API Google Wallet permite interagir com usuários usando vários tipos predefinidos de cartões: cartões de fidelidade, de ofertas, vales-presente, ingressos de eventos, bilhetes de transporte público e cartões de embarque. Cada tipo apresenta campos e recursos específicos ao caso de uso. No entanto, sabemos que eles podem não se adequar a todos os casos de uso. Por isso, criamos um tipo de cartão genérico. Como o nome sugere, esse tipo de cartão deve ser usado quando seu caso de uso não se encaixar em nenhum dos outros tipos especializados. 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
• Cartões de seguro
• Reservas de vários tipos

Você pode usar cartões genéricos para qualquer caso de uso que possa ser apresentado ao usuário na forma de um cartão com até três linhas de informações, com uma seção de detalhes e um código de barras opcionais, desde que se encaixe na Política de Uso aceitável.

A API Google Wallet permite criar o seguinte:

• Classes de cartões. Pense nas classes como modelos com informações comuns que todos os cartões em um programa ou evento têm. Todos os objetos de cartões pertencem a uma classe.
• Os objetos de cartões têm uma finalidade concreta associada à sua atividade como empresa e aos usuários, como cartões de estacionamento ou cartões de inscrição de academia. Cada um desses itens é associado a uma classe definida anteriormente e herda propriedades comuns dela.

Este codelab vai fornecer uma classe predefinida e ensinar você a definir o JSON de um objeto de cartão, incluindo o botão "Adicionar à Carteira do Google" no app Android, que permite aos usuários salvar o cartão na Carteira do Google.

Para ver mais informações sobre como incluir um botão "Adicionar à Carteira do Google" em um app Android ou a respeito da API Google Wallet, acesse a documentação para desenvolvedores da Carteira do Google.

Pré-requisitos

• Um computador com o Android Studio instalado.
• Saber criar e executar um projeto no Android Studio.
• Ter o git instalado.

O que você vai aprender

• Como adicionar o SDK da Carteira do Google ao app Android.
• Como verificar se a API Wallet está disponível.
• Como implementar uma IU que permita ao usuário adicionar um cartão à Carteira do Google.

2. Começar a configuração

Criar uma conta de emissor temporária

Antes de criar cartões para os usuários, você precisa criar uma conta de emissor, ativar a API Wallet e criar uma classe. Tudo isso pode ser feito com o Business Console do Google Pay. Você só vai poder acessá-lo quando o processo de aprovação for concluído. Sendo assim, criaremos uma conta de emissor temporária e uma classe de cartão para você neste codelab.

Crie a conta de teste com um endereço de e-mail que você possa usar com o dispositivo móvel onde planeja testar a integração.

1. Clique em Criar uma conta de emissor temporária e uma classe de exemplo.

Observação: não use essa classe ou a conta temporária para fins de produção. O acesso a contas temporárias é limitado a sete dias.

2. Anote os IDs do emissor e da classe, porque vão ser necessários nas próximas etapas.

Clonar o repositório git

Clone o repositório git, que contém o projeto Android que você vai editar, usando o comando abaixo:

git clone -b wallet-lab [e-mail]:google-pay/android-quickstart.git

Abrir no Android Studio

Abra o Android Studio, escolha "Open" na tela de boas-vindas e selecione a pasta kotlin no repositório recém-clonado para abrir como um projeto.

3. Como adicionar o SDK da Carteira do Google ao app

O projeto Android contém uma atividade vazia que vamos editar em breve, mas primeiro vamos adicionar o SDK da Carteira do Google como uma dependência. No Android Studio, selecione o script "build.gradle" no nível do módulo e adicione as linhas abaixo à seção dependencies:

dependencies {
    ...
    implementation 'com.google.android.gms:play-services-pay:16.0.3'
}

Depois dessa mudança, clique no botão "Sync Project" do Gradle no canto direito de cima do Android Studio.

4. Como incluir o botão "Adicionar à Carteira do Google"

Em seguida, você vai incluir o botão "Adicionar à Carteira do Google" à atividade. Os recursos do botão já foram adicionados ao projeto, basta os adicionar ao arquivo de layout. Para fazer isso, recomendamos criar um layout separado com o botão:

add_to_google_wallet_button.xml

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:clickable="true"
    android:focusable="true"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:contentDescription="@string/add_to_google_wallet_button_content_description">
    <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>

O botão vai ficar assim:

Se você estiver adicionando o botão a um aplicativo próprio, acesse a página de diretrizes do botão e faça o download dos arquivos SVG do botão com os temas de cores e idiomas que atendem às suas necessidades. Inclua imagens apenas em configurações com suporte. É possível importar recursos vetoriais no Android Studio em File > New > Vector Asset. Selecione "Local file" no assistente, dê um nome ao botão (por exemplo, add_to_google_wallet_button) e localize o arquivo no seu drive local para importar.

Em seguida, inclua o botão no arquivo de layout:

<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"/>

5. Como verificar se a API está disponível

Agora, é hora de começar a programar. No Android Studio, abra o arquivo em que você vai fazer chamadas da API Google Wallet, que é o arquivo CheckoutActivity.kt, se estiver usando o aplicativo de exemplo. Em seguida, instancie um objeto PayClient como membro da classe. Este objeto ajuda você a fazer chamadas da API Google Wallet. O método getClient recebe o contexto da classe de instanciação, que neste caso é a atividade de chamada.

private lateinit var walletClient: PayClient

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    walletClient = Pay.getClient(this)
    ...
}

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 MVVM, coloque a lógica de negócios relacionada à IU na sua atividade ou fragmento (como elementos da IU e o resultado da atividade). Além disso, coloque a lógica operacional no modelo de visualização (como a instanciação do cliente e gatilhos de chamadas de rede).

Em seguida, confira se o SDK e o aplicativo da Carteira do Google estão disponíveis no dispositivo. Crie um novo método na classe (por exemplo: fetchCanUseGoogleWalletApi) para determinar se a API Google Wallet está disponível e outro para reagir ao resultado e mostrar o botão "Adicionar à Carteira do Google" se a API estiver disponível:

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
        }
}

Há vários motivos possíveis 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.

Por fim, chame o método fetchCanUseGoogleWalletApi no método onCreate para determinar se a API Google Wallet está disponível:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    ...
    fetchCanUseGoogleWalletApi()
}

Agora, você vai ver o botão "Adicionar à Carteira do Google" na IU ao executar o app:

Se o botão "Adicionar à Carteira do Google" não aparecer, confira o erro retornado pelo método getPayApiAvailabilityStatus e os registros para saber mais. Se a API não estiver disponível, considere não mostrar o botão "Adicionar à Carteira do Google" e volte a um método alternativo para adicionar o cartão, como o JWT link. Lembre-se de que o usuário em questão pode se qualificar para usar a API no futuro.

6. Como adicionar um cartão à Carteira do Google

Agora que confirmou que a API Google Wallet está disponível, você pode oferecer a adição de cartões à Carteira do Google para os usuários. Antes de fazer isso, dê uma olhada no cartão criado neste workshop:

Esse layout usa a flexibilidade de cartões genéricos para criar um objeto que funciona tanto como um crachá de identificação quanto para um desafio onde os participantes precisam coletar pontos durante o evento. O objeto genérico tem esta aparência:

{
    "id": "999999.d1fa-4cca1...",
    "classId": "999999.a92b-129f...",
    "genericType": "GENERIC_TYPE_UNSPECIFIED",
    "hexBackgroundColor": "#4285f4",
    "logo": { ... },
    "cardTitle": { ... },
    "subheader": { ... },
    "header": { ... },
    "barcode": { ... },
    "heroImage": { ... },
    "textModulesData": []
}

Para inserir o objeto, a API espera um corpo JWT não assinado unindo o(s) novo(s) elemento(s):

{
    "iss": <owner-email-address>,
    "aud": "google",
    "typ": "savetowallet",
    "iat": <unix-time>,
    "origins": [],
    "payload": {
        "genericObjects": [],
        "genericClasses": [],
        ...
    }
}

Reúna todos esses elementos usando os valores recebidos anteriormente ao criar uma conta de emissor temporária e atribua o objeto resultante a uma variável na classe:

private val issuerEmail = "<insert-your-issuer-email-address>"
private val issuerId = "<insert-your-issuer-id>"
private val passClass = "<insert-your-class-id>"
private val passId = UUID.randomUUID().toString()

private val newObjectJson = """
    {
      "iss": "$issuerEmail",
      "aud": "google",
      "typ": "savetowallet",
      "iat": ${Date().time / 1000L},
      "origins": [],
      "payload": {
        "genericObjects": [
          {
            "id": "$issuerId.$passId",
            "classId": "$passClass",
            "genericType": "GENERIC_TYPE_UNSPECIFIED",
            "hexBackgroundColor": "#4285f4",
            "logo": {
              "sourceUri": {
                "uri": "https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg"
              }
            },
            "cardTitle": {
              "defaultValue": {
                "language": "en",
                "value": "Google I/O '22  [DEMO ONLY]"
              }
            },
            "subheader": {
              "defaultValue": {
                "language": "en",
                "value": "Attendee"
              }
            },
            "header": {
              "defaultValue": {
                "language": "en",
                "value": "Alex McJacobs"
              }
            },
            "barcode": {
              "type": "QR_CODE",
              "value": "$passId"
            },
            "heroImage": {
              "sourceUri": {
                "uri": "https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg"
              }
            },
            "textModulesData": [
              {
                "header": "POINTS",
                "body": "${Random.nextInt(0, 9999)}",
                "id": "points"
              },
              {
                "header": "CONTACTS",
                "body": "${Random.nextInt(1, 99)}",
                "id": "contacts"
              }
            ]
          }
        ]
      }
    }
    """

Se você observar a definição da classe, vai ver que as informações em textModulesData são referenciadas na classe. Isso define, de acordo com o modelo dela, como os campos aparecem no cartão resultante.

Esse é um objeto de teste criado para fins educativos. Não crie cartões próprios em um cliente público, como aplicativos para dispositivos móveis. Em vez disso, gere e insira os cartões em um cliente confidencial, como um servidor de back-end, ou use apps clientes com solicitações autenticadas e seguras como opção para buscá-los.

Por fim, volte ao método onCreate e adicione um gerenciador de cliques ao botão "Adicionar à Carteira do Google" para iniciar a operação usando o método savePasses no cliente:

private val addToGoogleWalletRequestCode = 1000

private lateinit var layout: ActivityCheckoutBinding
private lateinit var addToGoogleWalletButton: View

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Use view binding to access the UI elements
    layout = ActivityCheckoutBinding.inflate(layoutInflater)
    setContentView(layout.root)

    addToGoogleWalletButton = layout.addToGoogleWalletButton.root
    addToGoogleWalletButton.setOnClickListener {
        walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }

    ...
}

Com isso, você definiu o JSON do novo objeto usando os códigos do emissor e da classe criados anteriormente. Quando o usuário clicar no botão "Adicionar à Carteira do Google", payClient.savePasses vai ser chamado e solicitar que o usuário adicione o novo objeto de cartão à Carteira do Google:

7. Como processar o resultado

Quase tudo pronto. Por fim, processe o resultado da operação, bem-sucedida ou não. Substitua o método onActivityResult para conter o código abaixo:

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.
            }

            else -> {
                // Handle unexpected (non-API) exception
            }
        }
    }
}

Com esse código, você processa casos em que o cartão é adicionado ou quando o usuário cancela a ação e também todos os erros que podem ocorrer. Execute o aplicativo de novo para confirmar se você pode adicionar o cartão e processar o resultado como esperado.

8. Parabéns

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

Saiba mais

Confira uma integração completa no aplicativo de exemplo do GitHub (link em inglês) para ver um exemplo completo.

Criar uma conta de emissor

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 acesso à API Google Wallet e autorizar o aplicativo Android a emitir chamadas da API. Veja a documentação para saber mais.