Skip to content
Guía del Centro de ayuda · Plantillas de pasesFase de incorporación 2
5 min de lecturaVerificado 2026-11-16

Campos dinámicos y personalización

Conecta propiedades personalizadas y variables del sistema mediante {variableName} en zonas Apple y Google.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado1 / 2
Elementos clave de la interfaz

Autocompletado de variables dinámicas (Zoom)

Escribe «{» en cualquier campo de Valor para buscar e insertar atributos personalizados ({passStatus}) o campos del sistema ({storedValue}, {userProvidedId}).

Descripción general

La personalización de pases de monedero para miles o millones de titulares se apoya en Propiedades personalizadas (definiciones de esquema declaradas en su plantilla) combinadas con vínculos {variable} dentro del modelo Field en las zonas header, primary, secondary, auxiliary, back y footer. En el momento de generar o actualizar el pase, Passinstance rellena estos tokens desde el diccionario structured JSON attributes del registro del pase y formatea fechas, números, monedas y notificaciones push en pantalla de bloqueo de manera nativa para Apple Wallet y Google Wallet.

Al escribir una llave se abre el autocompletado de variables
Al escribir una llave se abre el autocompletado de variables

Arquitectura del sistema: hidratación e indexación de campos dinámicos

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
HIDRATACIÓN DINÁMICA DE CAMPOS Y SERIALIZACIÓN
ETAPA 01 REGISTRO DE PASE (Pass Model en database)
serialNumber: "PI-884920-AB"
attributes (structured JSON indexado vía GIN attribute search index): { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
ETAPA 02 MOTOR DE HIDRATACIÓN Y FORMATEO DE CAMPOS
Resuelve {firstName}, {pointsBalance}, {serialNumber}, {expirationDate}
Aplica numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle
Sanea attributedValue (permite <a href="..."> en el reverso de Apple)
Inyecta changeMessage con token %@ para alertas en pantalla bloqueo iOS
ETAPA 03A APPLE WALLET (pass.json)
"secondaryFields": [{ "key": "points_field", "label": "POINTS BALANCE", "value": 1250, "numberStyle": "PKNumberStyleDecimal" "changeMessage": "New balance: %@"
}]
ETAPA 03B GOOGLE WALLET (WalletObject)
"loyaltyPoints": { "label": "POINTS BALANCE", "balance": { "int": 1250 }
},
"textModulesData": [...]

Configuración paso a paso en el editor visual

  1. 1
    Abra la sección Propiedades personalizadas de la plantilla y haga clic en + Añadir propiedad.
  2. 2
    Defina exactamente la Clave de propiedad (por ejemplo, firstName, memberTier, validUntil), el Tipo de datos (field data type: text, number, currency, date, dateTime, time), las reglas de validación Obligatorio / Único y valores predeterminados opcionales de respaldo.
  3. 3
    Vuelva a Campos del anverso / reverso en el editor visual.
  4. 4
    Haga clic dentro del valor de cualquier campo y escriba { para abrir el menú de autocompletado donde aparecen tanto sus Atributos personalizados como los Tokens del sistema integrados (como {serialNumber}, {externalId}, {stamps}, {balance}, {tierName}, {expirationDate}).
  5. 5
    Cuando Apple Wallet y Google Wallet requieran distinto ajuste de etiquetas, configure opcionalmente una Anulación para Android por campo.
Chip de variable vinculada dentro del inspector de campos
Chip de variable vinculada dentro del inspector de campos

Importante: Mantenga las Claves de propiedad en formato camelCase iniciando en minúscula (holderName, validUntil). Esas claves exactas se convierten en los nombres de propiedad de la API dentro del objeto structured JSON attributes al emitir pases vía /api/v1/passes o al mapear columnas CSV en importaciones por lotes. Además, cualquier changeMessage configurado en un campo debe incluir el marcador %@ (por ejemplo, "Su saldo de puntos es ahora %@"), o iOS suprimirá silenciosamente la notificación de actualización en la pantalla de bloqueo.

Especificación completa del modelo Field

Cada campo vinculado a una plantilla mediante request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields mapeados a field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) admite las siguientes propiedades:

PropiedadTipoValores / Formato permitidosComportamiento y reglas por plataforma
keystringIdentificador único por pase (p. ej. balance_fld)Usado por iOS y Android para comparar diferencias entre actualizaciones push
labelstringTexto estático o {variable}Mostrado en color labelColor encima o debajo del valor
value`string \number`Texto estático, número, fecha ISO o {variable}Hidratado al emitir o actualizar desde Pass.attributes, externalId o tokens del sistema
changeMessagestringCadena que contiene %@ (p. ej. "Nivel actualizado a %@")Activa una alerta push nativa en la pantalla de bloqueo de iOS cuando cambia value; %@ se reemplaza por el nuevo valor formateado
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalControla la alineación horizontal en las columnas frontales de Apple Wallet
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatea cadenas de fecha ISO 8601 según la configuración regional del dispositivo
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormatea componentes horarios en la zona horaria local del titular
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormatea valores numéricos con separadores de miles y decimales propios del idioma
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneHabilita acciones interactivas al tocar (llamar, abrir URL, abrir Mapas, añadir evento al calendario) en el reverso
currencyCodestringCódigo ISO 4217 de 3 letras (EUR, USD, GBP, CHF)Formatea valores numéricos como importes monetarios localizados en Apple y Google Wallet
attributedValuestringCadena HTML de enlace (<a href="https://...">Etiqueta</a>)Compatible en backFields de Apple Wallet para mostrar enlaces web, tel: o mailto: clicables

Reglas de etiquetas de enlace attributedValue en Apple Wallet

Apple Wallet no renderiza HTML arbitrario (<b>, <div>, <script>) dentro de los campos de un pase. Solo se permiten etiquetas de anclaje <a href="...">...</a> dentro de attributedValue en los campos back. El serializador de Passinstance (apple-pass-field.serializer.ts) elimina automáticamente etiquetas HTML no compatibles y convierte las URL válidas en entradas clicables dentro de linksModuleData en Google Wallet.

attributes structured JSON a nivel de pase e indexación GIN en database

Cuando se crea o actualiza un pase, los pares clave-valor de atributos personalizados se guardan en la columna structured JSON attributes de la tabla pass. Para garantizar filtrados en menos de un milisegundo entre millones de pases, Passinstance mantiene un índice invertido generalizado dedicado en database (attribute search index) sobre pass.attributes.

Este índice impulsa:

  • Consultas de cohortes a alta velocidad mediante GET /api/v1/passes (filtrando por propiedades personalizadas como attributes.tier = "VIP" o attributes.city = "Berlin").
  • Segmentación de audiencias en tiempo real en PassProjectSegment y Automatización de flujos de trabajo.
  • Hidratación dinámica de variables sin costosas uniones de tablas relacionales.

Ejemplo de API: configurar campos dinámicos en una plantilla

Solicitud HTTP

PATCH /api/v1/templates/tmpl_01hxyz987654321 Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "fields": {
    "headerFields": [
      {
        "key": "wallet_balance",
        "label": "BALANCE",
        "value": "{creditBalance}",
        "currencyCode": "EUR",
        "textAlignment": "PKTextAlignmentRight",
        "changeMessage": "Your card balance was updated to %@"
      }
    ],
    "primaryFields": [
      {
        "key": "holder_name",
        "label": "MEMBER",
        "value": "{firstName} {lastName}",
        "textAlignment": "PKTextAlignmentLeft"
      }
    ],
    "secondaryFields": [
      {
        "key": "member_since",
        "label": "VALID UNTIL",
        "value": "{expirationDate}",
        "dateStyle": "PKDateStyleMedium",
        "timeStyle": "PKDateStyleNone"
      }
    ],
    "backFields": [
      {
        "key": "support_link",
        "label": "CUSTOMER CONCIERGE",
        "value": "https://artisan-roasters.example.com/support",
        "attributedValue": "<a href='https://artisan-roasters.example.com/support'>Contact VIP Concierge</a>"
      }
    ]
  }
}

Respuesta HTTP (200 OK)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_01hxyz987654321",
    "rowKind": "DRAFT",
    "updatedAt": "2026-11-15T11:20:00.000Z"
  },
  "statusCode": 200
}

A continuación, aprenda a validar los controles de preparación y promover borradores en Versiones de plantilla y publicación.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.