Google Wallet: la tarjeta del socio en Android

La integración de Google Wallet del club de fidelización de Connect Manager pone la tarjeta de socio en la app Google Wallet de los móviles Android, con el saldo al día, avisos en la propia tarjeta y el código que se escanea en el TPV Ágora para identificar al socio. Este manual explica al técnico cómo se organiza en Google (emisor, clase y objeto), qué se configura en cada club, cómo se actualiza y qué límites pone Google.

Qué hace la integración#

• Emite la tarjeta del club en Google Wallet: arriba el nombre del club y su logo, como título el «Nombre del programa», el saldo con su etiqueta y el código de socio en QR, PDF417 o Código 128 (o en texto, si se elige no poner código de barras). En los detalles: el nombre y el código del socio (Google los enseña siempre), hasta dos datos más, su membresía y su nivel.
• Guarda la marca del club en una «clase» de Google, una por club: nombre del programa, color de fondo, logo, imagen de portada, enlaces de interés y ubicaciones de los locales. Al guardar Monederos o Apariencia se sube a Google y se ve en todas las tarjetas del club, también en las ya guardadas.
• Guarda los datos de cada socio en su «objeto»: saldo, nombre, código, botón, datos de los detalles y franja del nivel. Se actualizan con cada movimiento y Google avisa al socio cuando cambia el saldo.
• Enseña el nivel con su color: Google no deja cambiar el fondo de una tarjeta suelta, así que el nivel va en una franja con su color y su nombre (1032 × 336 px) en el lugar de la portada.
• Manda los avisos de las campañas del canal «Tarjeta del móvil» como mensajes con notificación, que se quedan 30 días en los detalles de la tarjeta.
• Pone un botón en el frontal: «Ver mi perfil» (el área privada del socio) o «Pedir a domicilio» (la tienda online propia del grupo, si está publicada).
• Añade enlaces en los detalles: «Tu área privada», «Invitar por WhatsApp», los enlaces de interés del club y «Actualizar mi tarjeta».
• Avisa cerca de los locales: hasta 10 locales con su ubicación; Google avisa al socio al pasar cerca si lo tiene activado en su móvil.
• Anula la tarjeta (móvil perdido o socio de baja): pasa a inactiva.
• Emite las entradas de la agenda del club, con una clase propia por evento que se actualiza al editar el evento.

Qué no hace#

• Más de 3 avisos con notificación al día por tarjeta. A partir del tercero Google contesta con error de cuota y el aviso se guarda en los detalles, pero sin notificación. Según los límites de Google, el aviso de cambio de saldo cuenta para el mismo tope.
• Un color de fondo distinto por socio: el color es del club; el nivel va como franja.
• Saber si el socio guarda o borra la tarjeta: Google no lo comunica. Solo se sabe cuándo abrió el enlace para añadirla, y eso es lo que enseña su ficha.
• Guardar más de 5 avisos por socio (Google admite 10 por tarjeta; se dejan los 5 últimos).
• Usar la cuenta de Google del cliente: todas las tarjetas salen de la cuenta de emisor de Connect Manager.
• Imágenes en direcciones privadas: Google descarga logos y portadas desde sus servidores, así que tienen que estar en una dirección pública https.
• Llevar a todos los socios los cambios que viven en su tarjeta (datos de los detalles, código, botón): se reenvían solo a los socios que han abierto el enlace de Google. La marca de la clase sí llega a todos.

Requisitos#

• En el servidor de Connect Manager (lo mantiene FOS): el Issuer ID de la cuenta de emisor de Connect Manager en Google Wallet y la clave JSON de su cuenta de servicio, subida en base64. Se revisa con php artisan loyalty:google-wallet-check.
• Una dirección pública https del hub, desde la que Google pueda descargar el logo, la portada y las franjas de nivel.
• La cola de trabajos funcionando: las actualizaciones van encoladas.
• El club creado en Configuración → Portal público de clientes, con su «Título de la aplicación» (sale como nombre del emisor encima del título) y su logo.
• La integración con el TPV funcionando (ver Fidelización: conectar el club con Ágora) y un lector que lea el formato elegido: QR y PDF417 necesitan lector 2D o cámara; un láser 1D solo lee Código 128.
• Socios con Android y Google Wallet; para recibir los avisos, las notificaciones de Wallet activadas en el móvil.
• Permisos en el panel: «Fidelización: Activar por grupo» para editar Monederos y «Fidelización: Emitir wallet passes» para «Enviar wallet».

Quién hace qué. FOS mantiene la cuenta de emisor y la cuenta de servicio. El técnico configura el diseño en Monederos, elige el formato del código y hace las pruebas. El cliente aporta nombre del programa, colores, logos, portada y enlaces.

Datos que necesitamos#

Configuración paso a paso#

1. En el servidor de Connect Manager (FOS)#

1. Ejecuta php artisan loyalty:google-wallet-check. Comprueba el Issuer ID, que la clave se lee como JSON con su client_email y su private_key, y pide un token a Google. Tiene que terminar con «Token OAuth obtenido … Google Wallet autentica correctamente.».
2. Si sale invalid_grant, la clave de la cuenta de servicio se ha rotado o borrado en Google Cloud: FOS genera una nueva y la sube en base64.

2. En Connect Manager: el diseño de la tarjeta#

Ve a Configuración → Portal público de clientes, abre el club y entra en Monederos (o en Delivery propio → Tienda → Pases, que edita la misma tarjeta).

1. «Logotipo de los pases»: sube el «Logotipo para Apple/Google Wallet», cuadrado y con margen alrededor de la marca.
2. En «Selecciona el monedero a personalizar» elige Google Wallet (Android). Lo tocado en Apple también se guarda.
3. «Etiqueta del saldo (Apple y Google)».
4. «Apariencia y colores»: «Color de fondo de tarjeta» (el color del texto lo elige Google, blanco o negro, según el fondo), «Nombre del programa» e «Imagen de portada» (se recorta al centro a 3:1). Para quitarla, «Quitar la imagen de portada».
5. «Detalles y escáner»: «Dato en los detalles (1)» y «Dato en los detalles (2)» (el nombre y el código ya salen siempre, y el nivel y la membresía también si el socio los tiene) y «Formato de código escaneable»: Código QR (recomendado), PDF417 (código 2D), Código 128 (código de barras 1D) o Sin código de barras (se muestra el código de socio en texto).
6. «Detalles del pase»: «Enlaces de interés», «Código de invitación del socio», «Entrar al área privada desde el pase», «Botón del pase de Google» (Ver mi perfil o Pedir a domicilio; la segunda solo se puede elegir con la tienda online publicada), «Avisar cerca de los locales» y «Color del nivel en la tarjeta».
7. Guarda. Deben salir «Tarjeta de Google Wallet actualizada» (la marca, los enlaces del club y las ubicaciones llegan a todas las tarjetas en unos minutos) y, si hay socios con la tarjeta, «Actualizando los pases ya emitidos».

[!NOTE] Guardar la subpágina Apariencia también vuelve a subir la clase, porque la tarjeta hereda de ahí el color principal y el logo cuando no hay uno propio. Y cambiar la ubicación de un local en Delivery propio actualiza las ubicaciones de la clase.

3. Entregar la tarjeta a los socios#

Los mismos caminos que en Apple: el botón de Google Wallet del área privada, la bienvenida y el «Envío del wallet para descarga» por correo, WhatsApp (ver WhatsApp y Bird), Enviar wallet desde la ficha del socio, la pantalla final del portal de registro y «Mi cuenta» de la tienda online. En un móvil Android, la página del enlace lleva directamente a guardar la tarjeta en Google.

4. En Ágora#

Nada específico: el código de la tarjeta es el código de socio, que Ágora valida con la URL de validación de participantes.

Cómo funciona#

Emisor, clase y objeto#

Todas las tarjetas salen de la cuenta de emisor de Connect Manager. Cada club tiene una clase, loyalty_class_ más la dirección web (slug) del grupo, con su marca; y cada socio un objeto, customer_ más su número interno, con sus datos. La clase se actualiza para todo el club de una vez; el objeto, socio a socio.

Alta de la tarjeta#

El socio abre un enlace firmado. Connect Manager apunta que ese socio ha pedido la tarjeta de Google, compone un JWT con la clase del club y el objeto del socio, lo firma con la cuenta de servicio y lo manda al enlace de guardar de Google. Al pulsar «Guardar», Google crea el objeto. Google solo lee la clase del enlace si todavía no existe; si ya existía, se queda con la suya, y por eso la marca se sube aparte al guardar Monederos.

sequenceDiagram
    participant M as Móvil Android
    participant CM as Connect Manager
    participant G as Google Wallet
    M->>CM: Abre el enlace firmado
    CM->>CM: Apunta la petición y firma un JWT con clase y objeto
    CM-->>M: Redirige al enlace de guardar de Google
    M->>G: El socio pulsa Guardar
    G->>G: Crea el objeto del socio

Actualizaciones#

Cuando cambia algo del socio se encola una sincronización. El trabajo actualiza su objeto en la API de Google Wallet: estado activo, nombre, saldo, botón, datos de los detalles, enlaces, código y franja del nivel, pidiendo a Google que avise si cambia el saldo. Si el socio abrió el enlace pero no llegó a guardar la tarjeta, Google contesta 404 y se ignora. Un error de credenciales o de Google queda en el registro y el trabajo se reintenta hasta 3 veces, cada 30 segundos.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant G as API Google Wallet
    participant M as Móvil Android
    TPV->>CM: Factura con socio
    CM->>CM: Encola la actualización
    CM->>G: Actualiza el objeto del socio con el saldo
    alt El socio no guardó la tarjeta
        G-->>CM: 404, se ignora
    else Tarjeta guardada
        G->>M: Actualiza la tarjeta y avisa del saldo
    end

Avisos de campaña#

Una campaña del canal «Tarjeta del móvil» (Administración → Campañas) llega a los socios que han pedido la tarjeta de Google. Para cada uno se dejan en la tarjeta solo los últimos avisos guardados y se añade el nuevo como mensaje con notificación, visible 30 días. Si Google responde que se ha superado la cuota de avisos, se vuelve a mandar como mensaje sin notificación: queda en los detalles. Este canal se envía a 5 socios por segundo.

La marca del club#

Al guardar Monederos o Apariencia, Connect Manager crea o actualiza la clase del club en Google. Las direcciones de las imágenes llevan una versión, porque Google las guarda en caché por dirección: así un logo nuevo se descarga de verdad. Si la dirección del logo no es pública (un entorno de pruebas), la actualización no se envía y queda anotado en el registro.

Comprobar que funciona#

1. FOS: php artisan loyalty:google-wallet-check obtiene el token sin errores.
2. Guarda Monederos: sale «Tarjeta de Google Wallet actualizada».
3. Con un socio de prueba, pulsa Enviar wallet, abre el correo en un Android y guarda la tarjeta.
4. En la ficha del socio, pestaña «Wallet (Apple / Google)», aparece «Google Wallet: enlace del pase abierto el …».
5. Escanea la tarjeta en Ágora: el socio se identifica.
6. Añade 1 € de saldo: la tarjeta cambia y, con las notificaciones de Wallet activadas, el móvil avisa.
7. Cambia el color de fondo, guarda y comprueba que la tarjeta lo refleja en unos minutos.

Errores frecuentes y solución#

Preguntas frecuentes#

¿El restaurante necesita su propia cuenta de Google Wallet?#

No. Todas las tarjetas salen de la cuenta de emisor de Connect Manager; cada club tiene su clase con su marca.

¿Cómo cambio el color de la tarjeta de Google Wallet?#

Con «Color de fondo de tarjeta» en Monederos, para todo el club. Si el club tiene niveles con color, cada socio ve además una franja con el color y el nombre de su nivel.

¿Se actualiza el saldo de Google Wallet al pagar en Ágora?#

Sí. Al registrarse la factura se actualiza el objeto del socio y Google le avisa del nuevo saldo, si tiene las notificaciones de Wallet activadas.

¿Por qué un socio con Android no recibe la notificación de una campaña?#

Google permite 3 avisos con notificación al día por tarjeta; los siguientes se guardan sin avisar. También puede tener las notificaciones de Wallet apagadas o no haber guardado la tarjeta.

¿Puedo poner un botón para pedir a domicilio en la tarjeta de Google Wallet?#

Sí, eligiendo «Pedir a domicilio» en «Botón del pase de Google», si el grupo tiene su tienda online publicada. El área privada pasa entonces a los enlaces de los detalles.

¿Qué pasa con las tarjetas ya guardadas si cambio el logo?#

Al guardar se sube la clase del club y todas las tarjetas, nuevas y guardadas, muestran el logo nuevo en unos minutos.

Referencias#

• Ficha de Google Wallet en el catálogo
• Fidelización: conectar el club con Ágora
• Apple Wallet: la tarjeta del club en el iPhone
• WhatsApp y Bird: mensajes y campañas del club
• Documentación de Google Wallet para desarrolladores
• Tarjetas de fidelización en Google Wallet