Skip to content
Guia da Central de Ajuda · Modelos de passesFase de integração 2
5 min de leituraVerificado 2026-11-16

Campos dinâmicos e personalização

Associe propriedades personalizadas e variáveis de sistema com {variableName} nas zonas Apple e Google Wallet.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface1 / 2
Elementos-chave da interface

Preenchimento automático de variáveis dinâmicas (Zoom)

Digite «{» em qualquer campo de Valor para pesquisar e inserir atributos personalizados ({passStatus}) ou campos do sistema ({storedValue}, {userProvidedId}).

Visão geral

A personalização de passes para carteiras digitais para milhares ou milhões de titulares assenta em Propriedades Personalizadas (definições de esquema declaradas no modelo) combinadas com associações {variable} dentro do modelo Field nas zonas header, primary, secondary, auxiliary, back e footer. No momento da geração e atualização do passe, a Passinstance hidrata estes tokens a partir do dicionário structured JSON attributes do registo de passe e formata datas, números, moedas e notificações push no ecrã bloqueado nativamente para Apple Wallet e Google Wallet.

Digitar chaveta abre preenchimento automático de variáveis
Digitar chaveta abre preenchimento automático de variáveis

Arquitetura do sistema: Hidratação dinâmica de campos e indexação

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
HIDRATAÇÃO DINÂMICA DE CAMPOS E SERIALIZAÇÃO
ETAPA 01 REGISTO DE PASSE (Pass no database)
serialNumber: "PI-884920-AB"
attributes (structured JSON indexado via GIN attribute search index): { "firstName": "Sophia", "pointsBalance": 1250, "tier": "Platinum" }
ETAPA 02 MOTOR DE HIDRATAÇÃO E FORMATAÇÃO DE CAMPOS
Resolve {firstName}, {pointsBalance}, {serialNumber}, {expirationDate}
Aplica numberStyle, currencyCode (ISO 4217), dateStyle, timeStyle
Sanitiza attributedValue (permite <a href="..."> no verso Apple)
Injeta changeMessage com token %@ para alertas push no ecrã bloqueado 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": [...]

Configuração passo a passo no Editor Visual

  1. 1
    Abra a secção Propriedades personalizadas do modelo e clique em + Adicionar propriedade.
  2. 2
    Defina a Chave da Propriedade exata (por exemplo, firstName, memberTier, validUntil), Tipo de Dados (field data type: text, number, currency, date, dateTime, time), regras de validação Obrigatório / Único e valores predefinidos opcionais.
  3. 3
    Regresse a Campos Frente / Verso no Editor Visual.
  4. 4
    Clique dentro de qualquer valor de campo e digite { para abrir o menu de preenchimento automático que mostra tanto os seus Atributos Personalizados como os Tokens de Sistema integrados (tais como {serialNumber}, {externalId}, {stamps}, {balance}, {tierName}, {expirationDate}).
  5. 5
    Onde a Apple Wallet e a Google Wallet difiram na quebra de rótulos, configure opcionalmente uma Substituição Android por campo.
Chip de variável associada dentro do inspetor de campos
Chip de variável associada dentro do inspetor de campos

Importante: Mantenha as Chaves de Propriedade em camelCase minúsculo inicial (holderName, validUntil). Essas chaves exatas passam a ser os nomes das propriedades na API dentro do objeto structured JSON attributes ao emitir passes via /api/v1/passes ou mapear colunas CSV em importações em lote. Além disso, qualquer changeMessage configurada num campo tem de incluir o marcador %@ (ex.: "Your points balance is now %@"), caso contrário o iOS suprimirá silenciosamente a notificação de atualização no ecrã bloqueado.

Especificação completa do modelo Field

Cada campo associado a um modelo via request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields mapeados para field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) suporta as seguintes propriedades:

PropriedadeTipoValores permitidos / FormatoComportamento por plataforma e regras
keystringIdentificador único por passe (ex.: balance_fld)Utilizado pelo iOS e Android para calcular diferenças de valores entre atualizações push
labelstringLegenda estática ou {variable}Apresentado com labelColor acima ou abaixo do valor
value`string \number`Texto estático, número, data ISO ou {variable}Hidratado na emissão/atualização a partir de Pass.attributes, externalId ou tokens de sistema
changeMessagestringString contendo %@ (ex.: "Tier upgraded to %@")Despoleta alerta push nativo no ecrã bloqueado iOS quando value muda; %@ é substituído pelo novo valor formatado
textAlignmentPKTextAlignmentPKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNaturalControla o alinhamento horizontal nas colunas de campos frontais da Apple Wallet
dateStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormata strings de data ISO 8601 conforme o idioma/região do dispositivo do titular
timeStylePKDateStylePKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFullFormata componentes horários no fuso horário local do titular
numberStylePKNumberStylePKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOutFormata valores numéricos com separadores de milhares e decimais adaptados à região
dataDetectorTypesPKDataDetectorType[]PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNoneAtiva ações interativas ao tocar (ligar, abrir URL, abrir Mapas, adicionar evento ao calendário) em campos do verso
currencyCodestringCódigo ISO 4217 de 3 letras (EUR, USD, GBP, CHF)Formata valores numéricos como montantes monetários localizados na Apple e Google Wallet
attributedValuestringString de âncora HTML (<a href="https://...">Label</a>)Suportado em backFields da Apple Wallet para apresentar ligações clicáveis web, tel: ou mailto:

Regras da etiqueta âncora attributedValue na Apple Wallet

A Apple Wallet não apresenta HTML arbitrário (<b>, <div>, <script>) dentro dos campos do passe. Apenas etiquetas de âncora <a href="...">...</a> são permitidas dentro de attributedValue em campos back. O serializador da Passinstance (apple-pass-field.serializer.ts) remove automaticamente etiquetas HTML não suportadas e converte URLs válidos em entradas clicáveis linksModuleData na Google Wallet.

attributes structured JSON ao nível do passe e indexação database GIN

Quando um passe é criado ou atualizado, os pares chave-valor de atributos personalizados são armazenados na coluna structured JSON attributes da tabela pass. Para garantir filtragem em submilissegundos entre milhões de passes, a Passinstance mantém um Índice Invertido Generalizado dedicado do database (attribute search index) em pass.attributes.

Este índice alimenta:

  • Consultas rápidas de coortes via GET /api/v1/passes (filtragem por propriedades personalizadas como attributes.tier = "VIP" ou attributes.city = "Berlin").
  • Segmentação de público em tempo real em PassProjectSegment e Automação de Fluxos.
  • Hidratação dinâmica de variáveis sem junções relacionais dispendiosas.

Exemplo de API: Configurar campos dinâmicos num modelo

Pedido HTTP

PATCH /api/v1/templates/tmpl_01hxyz987654321 Cabeçalhos: 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>"
      }
    ]
  }
}

Resposta HTTP (200 OK)

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

De seguida, aprenda a validar os requisitos de conclusão e a promover rascunhos em Versões de modelos e publicação.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.