A Carteira do Google oferece ferramentas poderosas para personalizar a aparência e o layout de qualquer cartão, desde ingressos de eventos e cartões de embarque até cartões de fidelidade e vales-presente. Este guia oferece uma visão geral abrangente de como personalizar a experiência do usuário definindo a estrutura do card e mostrando informações dinâmicas e específicas do usuário.
Antes de começar, consulte a documentação de referência específica da API REST para seu tipo de cartão e confira uma lista completa dos campos disponíveis.
A Fundação: cardTemplateOverride
A principal ferramenta para personalizar o layout de um cartão é o objeto classTemplateInfo.cardTemplateOverride, que você define no recurso Class do cartão (por exemplo, EventTicketClass, LoyaltyClass). Esse objeto permite estruturar o cartão definindo linhas e os itens dentro delas, controle sobre como as informações são apresentadas.
Você pode consultar dados do recurso Class (para informações compartilhadas entre todos os usuários) e do recurso Object (para detalhes específicos do usuário).
1. Personalização com campos predefinidos da Carteira
Os campos predefinidos são as propriedades padrão disponíveis na API Google Wallet para um tipo específico de cartão. Esses campos têm nomes específicos e são renderizados pela Carteira de maneira consistente. Por exemplo, um código de barras, o nome de um evento, um número de voo ou o saldo de um vale-presente.
Ao fazer referência ao fieldPath desses campos predefinidos, você pode organizá-los em qualquer lugar do cartão.
Exemplo: exibição de detalhes específicos do cartão e do código de barras
Este exemplo de cartão tem uma "Linha superior" e três campos de dados na segunda linha. O primeiro item mostra os valores específicos do usuário no Object, como pontos ou número do assento. O segundo item mostra os detalhes do Class, como o nome de um evento ou o nível do programa de fidelidade, e o terceiro mostra novamente os valores específicos do usuário do Object, como ponto secundário ou número da seção / treinador.
Definição de classe:
...
"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",
...
Definição de objeto
...
"loyaltyPoints": {
"balance": {
"string": "1500"
},
"label": "Points"
},
"secondaryLoyaltyPoints" : {
"balance": {
"money": {
"micros" : "28250000",
"currencyCode": "USD",
}
},
"label": "Balance"
}
...
Formatar campos de data e hora
Para qualquer campo de data ou hora em cartões compatíveis, é possível especificar um formato personalizado usando a propriedade dateFormat. Isso permite controlar como a data é mostrada no cartão, como apenas a hora, a data e a hora completas ou apenas a data. Se dateFormat não for especificado, um formato padrão será usado.
"fields": [
{
"fieldPath": "object.validTimeInterval.start.date",
"dateFormat": "DATE_ONLY"
}
]
Para uma lista completa de formatos disponíveis, consulte a documentação do DateFormat.
2. Personalização com campos definidos pelo desenvolvedor
Para ter mais flexibilidade, a Carteira do Google permite criar seus próprios campos de dados personalizados usando textModulesData. É perfeito para mostrar informações exclusivas que não se encaixam nos campos predefinidos, como observações curtas personalizadas, benefícios para membros ou detalhes específicos de um local.
Defina um item textModulesData com um id exclusivo no Object ou Class e faça referência a esse id no cardTemplateOverride.
Estruturar linhas de cards
É possível criar um cartão com um, dois ou três itens de dados por cartão, o que permite organizar as informações de maneira lógica. Não há um limite rígido para o número de linhas que você pode adicionar, mas, para uma experiência do usuário mais limpa, considere o que é mais importante mostrar na frente do card.
- Prática recomendada:para informações complementares, use a visualização de detalhes do cartão ou outros recursos da Carteira, como
messages,linksModuleDataoulinkedOfferIds. Isso mantém a visualização principal do cartão organizada.
Exemplo: uma linha de três itens com dados personalizados
Crie uma linha para mostrar detalhes personalizados. Para um cartão fidelidade, isso pode ser pontos, nível e saldo. Para um ingresso de evento, pode ser "Seção", "Fila" e "Assento".
Definição de classe:O cardTemplateOverride faz referência a três IDs exclusivos: detail1, detail2 e 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",
Definição de objeto:o Object fornece os dados e os IDs correspondentes 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"
}
]
...
Dados de classe x objeto para variações
É possível combinar dados de classe e de objeto para criar cartões dinâmicos e personalizados. Isso é útil para criar versões diferentes do mesmo cartão.
- Nível da classe
textModulesData:use para detalhes que são iguais para um grupo de usuários (por exemplo, uma mensagem "Bem-vindo ao VIP" para todos os portadores de ingressos VIP). textModulesDatano nível do objeto:use isso para detalhes específicos de um usuário (por exemplo, "Jane, seu assento tem uma visão restrita").
Exemplo: exibição de passes específicos de nível
É possível criar diferentes recursos Class para diferentes variações de cartão, como "Entrada geral" x "VIP" para um evento ou "Econômica" x "Executiva" para um voo. Cada classe pode ter um design exclusivo (imagem principal, cor) e texto padrão.
 |
 |
 |
| Membro que começa com o Silver | O participante fez upgrade para o nível Ouro | Outro membro no nível Diamante |
Conteúdo na visualização de detalhes do item
Os campos de linksModuleData e imageModulesData não são renderizados na frente do cartão quando são referenciados em cardTemplateOverride. Esse conteúdo é exibido automaticamente na visualização Detalhes do cartão (o "verso do cartão"), oferecendo aos usuários melhor acesso a links de atendimento ao cliente, imagens promocionais, termos e condições e outras informações complementares.
3. Além da frente do card: outras substituições de modelo
O objeto classTemplateInfo oferece mais do que apenas cardTemplateOverride. Você pode personalizar outras partes da experiência da Carteira do Google para oferecer uma apresentação mais rica e intuitiva dos seus cartões.
Para conferir todos os detalhes sobre as substituições disponíveis, consulte a documentação de referência do ClassTemplateInfo.
listTemplateOverride: personaliza o layout da linha na visualização de lista principal do app Carteira do Google, permitindo que você destaque os campos mais importantes antes mesmo de um usuário abrir o cartão.detailsTemplateOverride: estrutura as linhas e o layout da visualização "Detalhes do cartão" (o verso do cartão), oferecendo um espaço flexível para informações complementares, links e texto.cardBarcodeSectionDetails: permite personalizar a seção de código de barras no cartão.