La Billetera de Google ofrece herramientas potentes para personalizar la apariencia y el diseño de cualquier pase, desde entradas para eventos y tarjetas de embarque hasta tarjetas de lealtad y de regalo. En esta guía, se proporciona una descripción general completa de cómo puedes personalizar la experiencia del usuario definiendo la estructura de la tarjeta y mostrando información dinámica específica para el usuario.
Antes de comenzar, asegúrate de consultar la documentación de referencia específica de la API de REST para tu tipo de pase y ver la lista completa de los campos disponibles.
La Fundación: cardTemplateOverride
La herramienta principal para personalizar el diseño de un pase es el objeto classTemplateInfo.cardTemplateOverride, que se define en el recurso Class del pase (p.ej., EventTicketClass, LoyaltyClass). Este objeto te permite estructurar el pase definiendo filas y los elementos que contienen, lo que te brinda control sobre cómo se presenta la información.
Puedes hacer referencia a los datos del recurso Class (para la información compartida entre todos los usuarios) y del recurso Object (para los detalles específicos del usuario).
1. Personalización con campos predefinidos de la Billetera
Los campos predefinidos son las propiedades estándar disponibles en la API de Google Wallet para un tipo de pase específico. Estos campos tienen nombres específicos y Wallet los renderiza de manera coherente. Entre los ejemplos, se incluyen un código de barras, el nombre de un evento, un número de vuelo o el saldo de una tarjeta de regalo.
Si haces referencia al fieldPath de estos campos predefinidos, puedes organizarlos en cualquier lugar de tu pase.
Ejemplo: Cómo mostrar el código de barras y los detalles específicos del pase
Este ejemplo de pase tiene una "fila superior" y 3 campos de datos dentro de la 2ª fila. El primer elemento muestra los valores específicos del usuario del Object, como los puntos o el número de asiento específicos para el usuario. El segundo elemento muestra los detalles de Class, como el nombre de un evento o el nivel del programa de lealtad, y el tercero vuelve a mostrar los valores específicos del usuario de Object, como el punto o la sección secundarios, o el número de entrenador.
Definición de la clase:
...
"classTemplateInfo": {
"cardTemplateOverride": {
"cardRowTemplateInfos": [
{
"threeItems": {
"startItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.loyaltyPoints.label",
"fieldPath": "object.loyaltyPoints.balance",
}
]
}
},
"middleItem": {
"firstValue": {
"fields": [
{
"fieldPath": "class.rewardsTierLabel",
"fieldPath": "class.rewardsTier",
}
]
}
},
"endItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.secondaryLoyaltyPoints.label",
"fieldPath": "object.secondaryLoyaltyPoints.balance",
}
]
}
}
}
},
]
}
}
...
"rewardsTier": "Gold",
"rewardsTierLabel": "Tier",
...
Definición del objeto
...
"loyaltyPoints": {
"balance": {
"string": "1500"
},
"label": "Points"
},
"secondaryLoyaltyPoints" : {
"balance": {
"money": {
"micros" : "28250000",
"currencyCode": "USD",
}
},
"label": "Balance"
}
...
Cómo dar formato a los campos de fecha y hora
Para cualquier campo de fecha o hora en los pases admitidos, puedes especificar un formato personalizado con la propiedad dateFormat. Esto te permite controlar cómo se muestra la fecha en el pase, por ejemplo, mostrar solo la hora, la fecha y la hora completas, o solo la fecha. Si no se especifica dateFormat, se usará un formato predeterminado.
"fields": [
{
"fieldPath": "object.validTimeInterval.start.date",
"dateFormat": "DATE_ONLY"
}
]
Para obtener una lista completa de los formatos disponibles, consulta la documentación de DateFormat.
2. Personalización con campos definidos por el desarrollador
Para una mayor flexibilidad, la Billetera de Google te permite crear tus propios campos de datos personalizados con textModulesData. Esto es ideal para mostrar información única que no cabe en los campos predefinidos, como notas cortas personalizadas, beneficios para miembros o detalles específicos de la ubicación.
Defines un elemento textModulesData con un id único en Object o Class y, luego, haces referencia a ese id en cardTemplateOverride.
Cómo estructurar filas de tarjetas
Puedes diseñar un pase con uno, dos o tres elementos de datos por pase, lo que te permite organizar la información de forma lógica. No hay un límite estricto para la cantidad de filas que puedes agregar, pero, para brindar una experiencia del usuario eficiente, considera qué es lo más importante que se debe mostrar en la cara de la tarjeta.
- Práctica recomendada: Para obtener información complementaria, usa la vista de detalles del pase o cualquier otra función de la Billetera, como
messages,linksModuleDataolinkedOfferIds. Esto mantiene la vista principal del pase despejada.
Ejemplo: Una fila de tres elementos con datos personalizados
Crea una fila para mostrar detalles personalizados. En el caso de una tarjeta de lealtad, podrían ser puntos, nivel y saldo. En el caso de un boleto para un evento, podrían ser "Sección", "Fila" y "Asiento".
Definición de la clase:
cardTemplateOverride hace referencia a tres IDs únicos: detail1, detail2 y detail3.
...
"classTemplateInfo": {
"cardTemplateOverride": {
"cardRowTemplateInfos": [
{
"oneItem": {
"item": {
"firstValue": {
"fields": [
{
"fieldPath": "object.accountName",
}
]
}
}
}
},
{
"threeItems": {
"startItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.loyaltyPoints.label",
"fieldPath": "object.loyaltyPoints.balance",
}
]
}
},
"middleItem": {
"firstValue": {
"fields": [
{
"fieldPath": "class.rewardsTierLabel",
"fieldPath": "class.rewardsTier",
}
]
}
},
"endItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.secondaryLoyaltyPoints.label",
"fieldPath": "object.secondaryLoyaltyPoints.balance",
}
]
}
}
}
},
{
"threeItems": {
"startItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.textModulesData['row1left']",
}
]
}
},
"middleItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.textModulesData['row1mid']"
}
]
}
},
"endItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.textModulesData['row1right']"
}
]
}
}
}
},
{
"twoItems": {
"startItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.textModulesData['mem_since']",
}
]
}
},
"endItem": {
"firstValue": {
"fields": [
{
"fieldPath": "object.textModulesData['park']",
}
]
}
}
}
},
]
}
}
...
"rewardsTier": "Gold",
"rewardsTierLabel": "Tier",
Definición del objeto:
El objeto Object proporciona los datos y los IDs correspondientes para cada campo.
...
"accountName": "Lorenaisabel Aliwarringlen",
"loyaltyPoints": {
"balance": {
"string": "1500"
},
"label": "Points"
},
"secondaryLoyaltyPoints" : {
"balance": {
"money": {
"micros" : "28250000",
"currencyCode": "USD",
}
},
"label": "Balance"
},
"textModulesData": [
{
"header": "Visits",
"body": "17",
"id": "row1left"
},
{
"header": "Rides",
"body": "259",
"id": "row1mid"
},
{
"header": "Park hours",
"body": "140",
"id": "row1right"
},
{
"header": "Member since",
"body": "Mar 01, 2017",
"id": "mem_since"
},
{
"header": "Parking",
"body": "Included (Free)",
"id": "park"
}
]
...
Datos de clase y de objeto para las variaciones
Puedes combinar datos a nivel de la clase y del objeto para crear pases dinámicos y personalizados. Esto es útil para crear diferentes versiones del mismo pase.
textModulesDataa nivel de la clase: Usa esta opción para los detalles que son iguales para un grupo de usuarios (p.ej., un mensaje de "Bienvenido a VIP" para todos los titulares de entradas VIP).- A nivel del objeto
textModulesData: Usa esta opción para obtener detalles específicos de un usuario (p.ej., Jane, tu asiento tiene una vista restringida").
Ejemplo: Cómo mostrar pases específicos para cada nivel
Puedes crear diferentes recursos Class para distintas variaciones de pases, como "Entrada general" en comparación con "VIP" para un evento, o "Económica" en comparación con "Ejecutiva" para un vuelo. Cada clase puede tener un diseño único (imagen de héroe, color) y texto predeterminado.
 |
 |
 |
| Miembro a partir de Plata | Se actualizó la membresía a Oro | Otro miembro en el nivel diamante |
Contenido en la vista de detalles del pase
Los campos de linksModuleData y imageModulesData no se renderizan en el frente del pase cuando se hace referencia a ellos en cardTemplateOverride. Este contenido se muestra automáticamente en la vista Detalles del pase (el "dorso del pase"), lo que les brinda a los usuarios un mejor acceso a los vínculos de atención al cliente, las imágenes promocionales, los términos y condiciones, y otra información complementaria.
3. Más allá de la cara de la tarjeta: Otras anulaciones de plantillas
El objeto classTemplateInfo ofrece más que solo cardTemplateOverride. Puedes personalizar otras partes de la experiencia de la Billetera de Google para brindar una presentación más intuitiva y enriquecida de tus pases.
Para obtener todos los detalles sobre las anulaciones disponibles, consulta la documentación de referencia de ClassTemplateInfo.
listTemplateOverride: Personaliza el diseño de la fila en la vista de lista principal de la app de la Billetera de Google, lo que te permite destacar los campos más importantes incluso antes de que el usuario abra su pase.detailsTemplateOverride: Estructura las filas y el diseño de la vista “Detalles del pase” (el reverso del pase), lo que te brinda un espacio flexible para información complementaria, vínculos y texto.cardBarcodeSectionDetails: Te permite personalizar la sección del código de barras en el pase.