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

1. Introducción

Descripción general

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, viene con campos y funciones específicos de casos 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 en el que se pueda presentar lo siguiente:

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

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.

Todas las clases y los objetos de pases deben cumplir con la Política de Uso Aceptable.

Pasa clases y objetos

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

Tipo	Descripción
Clase de pase	Una plantilla para un objeto pase individual. Contiene información común a todos los objetos de pase que pertenecen a esta clase.
Pasar objeto	Una instancia de una clase de pase exclusiva para un ID de usuario

Acerca de este codelab

En este codelab, completarás las siguientes tareas.

1. Crea una nueva cuenta de entidad emisora en el modo de demostración
2. Crea una cuenta de servicio para emitir pases
3. Cómo crear una nueva clase de pase genérico
4. Crea un nuevo objeto Pass
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. Cómo controlar el resultado de guardar el pase

Requisitos previos

• Android Studio
• Git
• Una Cuenta de Google con acceso a la consola de Google Cloud
• Node.js (versión 10 o una posterior)

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 en algún momento del codelab no puedes avanzar, el repositorio de GitHub google-pay/wallet-android-codelab contiene una solución completa a modo de referencia.

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 pases que se pueden agregar a las billeteras de los usuarios. A continuación, crearás un proyecto de Google Cloud y una cuenta de servicio. Estos se usarán para crear de manera programática clases y objetos de pases de la misma manera que un servidor de backend. Por último, autorizarás a la cuenta de servicio de Google Cloud para que administre pases en la cuenta de la entidad emisora de la Billetera de Google.

Es posible crear clases de pases y objetos dentro de clientes públicos como aplicaciones para dispositivos móviles. Sin embargo, es más seguro crear pases en un cliente privado, como un servidor de backend, o recuperarlos de las aplicaciones cliente a través de solicitudes autenticadas y seguras.

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

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

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

1. Abre la tarjeta Google Pay & Consola de la Billetera
2. Sigue las instrucciones en pantalla para crear una cuenta de entidad emisora
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 de entidad emisora 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. Habilitar la API de la Billetera de Google (también conocida como API de Google Pay for Passes) en tu proyecto

Cree una cuenta de servicio y una clave

Se necesitan 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. Esta contiene una clave privada que identifica tu aplicación como la cuenta de servicio. Esta clave es sensible, por lo que debes mantenerla confidencial.

Ten cuidado cuando uses una cuenta de servicio existente para este codelab, ya que puede tener permisos para otros recursos que no son necesarios.

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 solicitará 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 para un proyecto de Google Cloud.

1. Sigue las instrucciones en la documentación de claves de cuenta 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 línea de comandos (Windows) (es posible que debas iniciar una nueva sesión si ya tienes una abierta).

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Autoriza la cuenta de servicio

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

1. Abre la tarjeta Google Pay & Consola de la Billetera
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., [e-mail])
5. En el menú desplegable Nivel de acceso, selecciona Desarrollador o Administrador.
6. Selecciona Invitar.

3. Cómo crear 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, este heredará las propiedades definidas en la clase.

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 insignia de identidad y como rastreador de puntos de desafío. Cuando se cree un objeto pass a partir de esta clase, se verá como el siguiente gráfico.

En el gráfico, se ilustra un pequeño subconjunto de propiedades que se pueden configurar en un pase. Consulta la plantilla de pases genérica para ver cómo las diferentes propiedades de pases afectan la experiencia del usuario.

Las clases de pases pueden crearse directamente en las Cuentas de Google Pay y Consola de la Billetera o la API de la Billetera de Google. 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 pases.

1. Clona el repositorio de GitHub google-pay/wallet-android-codelab de GitHub en tu estación de trabajo local.

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

2. Abre el repositorio clonado en tu terminal o ventana 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 el ID de entidad emisora de la tarjeta de Google Pay. Consola de la Billetera

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

7. En la terminal o ventana de línea de comandos, ejecuta la secuencia de comandos generic_class.js

   node generic_class.js
   

Cuando se ejecute tu código, se creará una nueva clase de pase y se mostrará el ID de clase. El ID de clase se compone del ID de la entidad emisora seguido de un sufijo definido por el desarrollador. En este caso, el sufijo se establece en codelab_class (el ID de clase serí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 el botón Agregar a la Billetera de Google en la página de un producto.

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 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 separado. Una vez que lo agregues, el botón se verá de la siguiente manera.

Si quieres agregar el botón a tu propia aplicación, consulta los Lineamientos de marca para descargar los archivos SVG del botón con los idiomas que se ajusten a tus necesidades. Asegúrate de incluir solo gráficos para las configuraciones compatibles. Puedes importar recursos vectoriales en Android Studio en File > Nuevo > Vector Asset. En el asistente, selecciona Local file, ingresa un nombre (p.ej., add_to_google_wallet_button) y busca el archivo en tu estación de trabajo.

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 es compatible con la API de la Billetera de Google, es posible que se genere 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 una posible confusión. Existen varios motivos por los que la API podría no estar disponible, por ejemplo, que las versiones de Android o de los Servicios de Google Play 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 verifica 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, el botón se ocultará.

Considera ubicar la lógica empresarial específica del dominio de forma adecuada si usas otros patrones de diseño. Por ejemplo, si usas el patrón Model-View-ViewModel (MVVM), coloca la lógica empresarial relacionada con la IU en tu Activity o Fragment (p.ej.: elementos de la IU y resultados de actividad) y la lógica operativa de tu ViewModel (p.ej., creación de instancias de clientes y activadores de llamadas de red).

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

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

   de 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 controle 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, ahora deberías ver el botón Add to Google Wallet en la IU.

Si el botón Agregar a la Billetera de Google no aparece, revisa el error que muestra el método getPayApiAvailabilityStatus y los registros para obtener más información. Es posible que el usuario en cuestión sea apto para usar la API en el futuro.

7. Crea un objeto de pase genérico

Si tu cuenta de entidad emisora está en modo de demostración, solo podrás emitir pases para los usuarios de prueba. Si ejecutas la app con una dirección de correo electrónico diferente, no podrás agregar el pase a tu billetera.

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

Crea el objeto pass en el servidor de backend

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

Crea el objeto Pass cuando el usuario lo agregue a su billetera

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

1. Abre el archivo backend/generic_pass.js.
2. Reemplaza el valor de issuerId por el ID de entidad emisora de la tarjeta de Google Pay. Consola de la Billetera

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

3. En tu terminal o símbolo de la línea de comandos, ejecuta el archivo generic_pass.js

   node generic_pass.js
   

4. Copia el token de salida en tu portapapeles o en un editor de texto.

Cuando se ejecute tu código, definirá un nuevo objeto pass y lo incorporará a un JWT. Luego, el JWT se firma con la clave de la cuenta de servicio que creaste anteriormente. 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, el sistema de backend sería responsable de crear los JWT y mostrarlos a los clientes. En este codelab, la secuencia de comandos generic_pass.js emula este comportamiento y “devuelve” un token que puedes usar 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 pedirle 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. Configura 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 Resultado de savePassesJwt

En el paso final de este codelab, configurarás tu app para controlar 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 tu app para confirmar que puedes agregar el pase y controlar el resultado como se espera.

10. Felicitaciones

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 google-pay/wallet-android-codelab.

Crea pases y solicita acceso de producción

Cuando tengas todo listo para emitir tus propios pases en producción, ve a la página Google Pay y Consola de la Billetera para solicitar acceso a producción y autorizar la app para Android.

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