Crea pases en Android con la API de la Billetera de Google

Crea pases en Android con la API de la Billetera de Google

Acerca de este codelab

subjectÚltima actualización: ene 19, 2023
account_circleEscrito por Nick Alteen

1. Introducción

La API de la Billetera de Google te permite interactuar con los usuarios a través de varios tipos de pases: tarjetas de lealtad, ofertas, tarjetas de regalo, entradas para eventos, boletos de transporte público, tarjetas de embarque y mucho más. Cada tipo de pase o clase de pase incluye campos y funciones específicos del caso de uso para mejorar la experiencia del usuario.

Sin embargo, es posible que no se adapten a todos los casos de uso. Para crear una experiencia más personalizada, puedes usar el tipo de pase genérico. Estos son algunos ejemplos de casos de uso para el tipo de pase genérico:

  • Pases de estacionamiento
  • Tarjetas de membresía de biblioteca
  • Cupones de saldo
  • Tarjetas de membresía de gimnasio
  • Reservas

Puedes usar pases genéricos para cualquier caso de uso que se pueda presentar con lo siguiente:

  • Hasta tres filas de información
  • Gráfico de código de barras (opcional)
  • Sección de detalles (opcional)

Un dispositivo con Android que muestra el flujo de aprovisionamiento de Agregar a la Billetera de Google

Para obtener más información sobre la API de la Billetera de Google o sobre cómo agregar el botón Agregar a la Billetera de Google a una aplicación para Android, consulta la documentación para desarrolladores de la Billetera de Google.

Pasa clases y objetos

La API de la Billetera de Google expone métodos para crear lo siguiente:

Tipo

Descripción

Clase de pase

Es una plantilla para un objeto de pase individual. Contiene información común a todos los objetos de pase que pertenecen a esta clase.

Pasa el objeto

Es una instancia de una clase de pase que es única para un ID de usuario.

Acerca de este codelab

En este codelab, completarás las siguientes tareas.

  1. Crea una nueva cuenta de emisor en el modo de demostración
  2. Crea una cuenta de servicio para emitir pases
  3. Crea una nueva clase de pase genérico
  4. Crea un objeto de pase nuevo
  5. Crea un botón Agregar a la Billetera de Google para guardar un pase
  6. Cómo mostrar el botón en tu app para Android
  7. Controla el resultado de guardar el pase

Requisitos previos

Objetivos

Después de completar este codelab, podrás hacer lo siguiente:

  • Agrega el SDK de la Billetera de Google a tu app para Android
  • Comprueba si la API de la Billetera de Google está disponible en un dispositivo con Android
  • Crea un botón Agregar a la Billetera de Google

Asistencia

Si te bloqueas en algún momento del codelab, el repositorio de GitHub google-pay/wallet-android-codelab contiene una solución completa para que la consultes.

2. Configuración

En este paso, crearás una cuenta de entidad emisora en modo de demostración. Esto te permitirá crear clases y objetos de pase que se puedan agregar a las billeteras de los usuarios. A continuación, crearás un proyecto y una cuenta de servicio de Google Cloud. Se usarán para crear clases y objetos de pase de manera programática de la misma manera que un servidor de backend. Por último, autorizarás a la cuenta de servicio de Google Cloud a administrar los pases en tu cuenta de emisor de la Billetera de Google.

Regístrate para obtener una cuenta de entidad emisora de la API de la Billetera de Google

Se necesita una cuenta de emisor para crear y distribuir pases para la Billetera de Google. Puedes registrarte en Google Pay & Wallet Console. Inicialmente, tendrás acceso para crear pases en modo de demostración. Esto significa que solo los usuarios de prueba específicos podrán agregar los pases que crees. Los usuarios de prueba se pueden administrar en Google Pay & Wallet Console.

Para obtener más información sobre el modo de demostración, consulta los Requisitos previos de pase genérico.

  1. Abre la Consola de Google Pay y la Billetera de Google.
  2. Sigue las instrucciones en pantalla para crear una cuenta de emisor
  3. Selecciona API de la Billetera de Google.
  4. Confirma que comprendes las condiciones del servicio y la política de privacidad
  5. Copia el valor del ID del emisor en un editor de texto o en otra ubicación.
  6. En la pestaña Administrar, selecciona Configurar cuentas de prueba.
  7. Agrega las direcciones de correo electrónico que usarás en este codelab.

Habilita la API de la Billetera de Google

  1. Accede a la consola de Google Cloud.
  2. Si aún no tienes un proyecto de Google Cloud, crea uno ahora (consulta Crea y administra proyectos para obtener más información).
  3. Habilita la API de la Billetera de Google (también conocida como API de Google Pay para Pases) para tu proyecto.

Cree una cuenta de servicio y una clave

Se necesita una cuenta de servicio y una clave de cuenta de servicio para llamar a la API de la Billetera de Google. La cuenta de servicio es la identidad que llama a la API de la Billetera de Google. La clave de la cuenta de servicio contiene una clave privada que identifica a tu aplicación como la cuenta de servicio. Esta clave es sensible, así que manténla en secreto.

Crea una cuenta de servicio

  1. En la consola de Google Cloud, abre Cuentas de servicio.
  2. Ingresa un nombre, un ID y una descripción para tu cuenta de servicio
  3. Selecciona CREAR Y CONTINUAR.
  4. Selecciona LISTO.

Crea una clave de cuenta de servicio

  1. Selecciona tu cuenta de servicio
  2. Selecciona el menú KEYS.
  3. Selecciona AGREGAR CLAVE y, luego, Crear clave nueva.
  4. Selecciona el tipo de clave JSON.
  5. Selecciona CREAR.

Se te pedirá que guardes el archivo de claves en tu estación de trabajo local. Asegúrate de recordar su ubicación.

Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

Los SDKs de Google usan la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para autenticarse como una cuenta de servicio y acceder a diferentes APIs de un proyecto de Google Cloud.

  1. Sigue las instrucciones de la documentación de claves de cuentas de servicio de Google Cloud para configurar la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.
  2. Verifica que la variable de entorno esté configurada en una nueva sesión de terminal (MacOS/Linux) o de línea de comandos (Windows) (es posible que debas iniciar una sesión nueva si ya tienes una abierta).
    echo $GOOGLE_APPLICATION_CREDENTIALS

Autoriza la cuenta de servicio

Por último, deberás autorizar a la cuenta de servicio para que administre los pases de la Billetera de Google.

  1. Abre la Consola de Google Pay y la Billetera de Google.
  2. Selecciona Usuarios.
  3. Selecciona Invitar a un usuario.
  4. Ingresa la dirección de correo electrónico de la cuenta de servicio (p. ej., test-svc@myproject.iam.gserviceaccount.com).
  5. Selecciona Desarrollador o Administrador en el menú desplegable Nivel de acceso.
  6. Selecciona Invitar.

3. Crea una clase de pase genérico

En este paso, crearás la clase base para tu pase. Cada vez que se cree un pase nuevo para un usuario, heredará las propiedades definidas en la clase de pase.

La clase de pase que crearás durante este codelab usa la flexibilidad de los pases genéricos para crear un objeto que funcione como una insignia de identidad y un rastreador de puntos de desafío. Cuando se cree un objeto de pase a partir de esta clase, se verá como el siguiente gráfico.

Las clases de pase se pueden crear directamente en Google Pay & Wallet Console o con la API de Google Wallet. En este codelab, crearás la clase de pase genérico con la API. Esto sigue el proceso que usaría un servidor de backend privado para crear clases de pase.

  1. Clona el repositorio de GitHub de google-pay/wallet-android-codelab en tu estación de trabajo local.
    git clone https://github.com/google-pay/wallet-android-codelab.git
  2. Abre el repositorio clonado en la terminal o en la instrucción de línea de comandos.
  3. Navega al directorio backend (estas secuencias de comandos imitan las acciones del servidor de backend).
    cd backend
  4. Instala las dependencias de Node.js
    npm install .
  5. En el directorio backend, abre generic_class.js.
  6. Reemplaza el valor de issuerId por tu ID del emisor de la Consola de Google Pay y la Billetera de Google.
    // TODO: Define Issuer ID
    let issuerId = 'ISSUER_ID';
  7. En la terminal o la línea de comandos, ejecuta la secuencia de comandos generic_class.js.
    node generic_class.js

Cuando se ejecute el código, se creará una nueva clase de pase y se mostrará el ID de la clase. El ID de clase está compuesto por el ID del emisor seguido de un sufijo definido por el desarrollador. En este caso, el sufijo se establece en codelab_class (el ID de clase se vería similar a 1234123412341234123.codelab_class). Los registros de salida también incluirán la respuesta de la API de la Billetera de Google.

4. Abre el proyecto en Android Studio

El repositorio de GitHub que clonaste contiene un proyecto de Android con una actividad vacía. En este paso, editarás esta actividad para incluir un botón Agregar a la Billetera de Google en una página de productos.

  1. Abre Android Studio.
  2. Selecciona Archivo y, luego, Abrir.
  3. Selecciona el directorio android en el repositorio.
  4. Selecciona Abrir.

Agrega el SDK de la Billetera de Google a tu app

  1. Abre el archivo de compilación de Gradle a nivel del módulo (android/app/build.gradle).
  2. Agrega el SDK de la Billetera de Google a la sección 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. Guarde el archivo.
  4. Selecciona File y, luego, Sync Project with Gradle Files.

5. Crea el botón para agregar a la Billetera de Google

En este paso, crearás un botón Agregar a la Billetera de Google y lo agregarás a una actividad existente. Los recursos del botón ya se incluyeron en el proyecto. Para incluir el botón, crearás un archivo de diseño independiente. Una vez agregado, el botón se verá de la siguiente manera.

El botón Agregar a la Billetera de Google

  1. Crea un nuevo archivo de diseño: app/src/main/res/layout/add_to_google_wallet_button.xml
  2. Agrega el siguiente contenido al nuevo archivo de diseño
    <?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. Incluye el diseño add_to_google_wallet_button.xml en el archivo de diseño de la actividad de confirmación de la 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. Comprueba si la API de la Billetera de Google está disponible

Si un usuario abre tu app en un dispositivo que no admite la API de la Billetera de Google, es posible que se cree una experiencia negativa cuando intente agregar el pase. Si el dispositivo del usuario no admite la API de la Billetera de Google, ocultar el botón Agregar a la Billetera de Google evita posibles confusiones. Existen varios motivos por los que la API puede no estar disponible, como que las versiones de los Servicios de Google Play o Android estén desactualizadas o que la Billetera de Google no esté disponible en el país del usuario.

En este paso, agregarás lógica a tu app que verifique si la API de la Billetera de Google está disponible en el dispositivo. Si es así, el botón se renderizará en la actividad. De lo contrario, se ocultará el botón.

  1. Abre el archivo CheckoutActivity.kt en app/src/main/java/com/google/android/gms/samples/wallet/activity/
  2. Crea una propiedad de clase para la instancia de PayClient
    // TODO: Create a client to interact with the Google Wallet API
    private lateinit var walletClient: PayClient
  3. Crea una instancia de la propiedad PayClient en el método onCreate.
    // TODO: Instantiate the client
    walletClient = Pay.getClient(this)
  4. Crea un método que verifique si el SDK y la API de la Billetera de Google están disponibles en el dispositivo y controla el 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. Llama al método fetchCanUseGoogleWalletApi en el método onCreate para verificar si la API de la Billetera de Google está disponible.
    // TODO: Check if the Google Wallet API is available
    fetchCanUseGoogleWalletApi()

Cuando ejecutes la app, deberías ver el botón Agregar a la Billetera de Google en la IU.

El botón Agregar a la Billetera de Google ahora aparece en la actividad de la app.

7. Crea un objeto de pase genérico

Ahora que verificaste que la API de la Billetera de Google está disponible, puedes crear un pase y solicitarle al usuario que lo agregue a su billetera. Existen dos flujos para crear objetos de pase para los usuarios.

Crea el objeto de pase en el servidor de backend

En este enfoque, el objeto de pase se crea en un servidor de backend y se muestra a la app cliente como un JWT firmado. Esta opción es más adecuada para los casos en los que la adopción de los usuarios es alta, ya que garantiza que el objeto exista antes de que el usuario intente agregarlo a su billetera.

Crea el objeto de pase cuando el usuario lo agrega a su billetera

En este enfoque, el objeto de pase se define y codifica en un JWT firmado en el servidor de backend. Luego, se renderiza un botón Agregar a la Billetera de Google en la app cliente que hace referencia al JWT. Cuando el usuario selecciona el botón, se usa el JWT para crear el objeto de pase. Esto es más adecuado para los casos en los que la adopción de los usuarios es variable o desconocida, ya que evita que se creen objetos de pase y no se usen. Este enfoque se usará en el codelab.

  1. Abre el archivo backend/generic_pass.js.
  2. Reemplaza el valor de issuerId por tu ID del emisor de la Consola de Google Pay y la Billetera de Google.
    // TODO: Define Issuer ID
    let issuerId = 'ISSUER_ID';
  3. En la terminal o la línea de comandos, ejecuta el archivo generic_pass.js.
    node generic_pass.js
  4. Copia el token de salida en el portapapeles o en un editor de texto.

Cuando se ejecute tu código, definirá un nuevo objeto de pase y lo incorporará en un JWT. Luego, la clave de la cuenta de servicio que creaste antes firma el JWT. Esto autentica la solicitud a la API de la Billetera de Google para que no sea necesario almacenar las credenciales en la app cliente.

En un entorno de producción, tu sistema de backend sería responsable de crear JWT y devolverlos a los clientes. En este codelab, la secuencia de comandos generic_pass.js emula este comportamiento y “muestra” un token para que lo uses en la app cliente.

8. Agrega el pase a la Billetera de Google

Ahora que verificaste que la API de la Billetera de Google está disponible y creaste un JWT firmado, puedes solicitarle al usuario que agregue el pase a su billetera. En este paso, agregarás un objeto de escucha al botón Agregar a la Billetera de Google que usa la API de la Billetera de Google para guardar el pase en la billetera del usuario.

  1. Abre el archivo app/src/main/CheckoutActivity.kt.
  2. Reemplaza el valor de token por el JWT que creaste anteriormente.
    // TODO: Save the JWT from the backend "response"
    private val token = "TOKEN"
  3. Crea una propiedad de clase para almacenar el código de solicitud
    // TODO: Add a request code for the save operation
    private val addToGoogleWalletRequestCode = 1000
  4. Establece un objeto de escucha para el botón Agregar a la Billetera de Google
    // TODO: Set an on-click listener on the "Add to Google Wallet" button
    addToGoogleWalletButton = layout.addToGoogleWalletButton.

    addToGoogleWalletButton.setOnClickListener {
      walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
    }

Cuando un usuario selecciona el botón Agregar a la Billetera de Google, se llama al método walletClient.savePassesJwt. Este método le solicita al usuario que agregue el nuevo objeto de pase a su Billetera de Google.

9. Controla el resultado de savePassesJwt

En el paso final de este codelab, configurarás tu app para que controle el resultado de la operación walletClient.savePassesJwt.

  1. Abre el archivo app/src/main/CheckoutActivity.kt.
  2. Anula el método onActivityResult para que contenga el siguiente 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
          }
        }
      }
    }

Ahora, tu app puede controlar las siguientes situaciones:

  • Se agregó correctamente el pase
  • Cancelación del usuario
  • Errores inesperados

Ejecuta la app para confirmar que puedes agregar el pase y controlar el resultado como se espera.

10. Felicitaciones

Ejemplo de objeto de pase genérico

Felicitaciones, integraste correctamente la API de la Billetera de Google en Android.

Más información

Consulta la integración completa en el repositorio de GitHub de google-pay/wallet-android-codelab.

Crea pases y solicita acceso a producción

Cuando esté todo listo para emitir tus propios pases en producción, ve a Google Pay & Wallet Console para solicitar acceso a producción y autorizar tu app para Android.

Consulta los Requisitos previos del SDK de Android para obtener más información.