Quase todos os cartões que você pode emitir para um usuário final salvar na Carteira do Google são definidos por dois componentes: uma classe de cartões e um objeto de cartões. Sempre que você emitir um cartão para um usuário, você vai precisar de uma instância de uma classe de cartões e de um objeto de cartões, que informa à API Google Wallet qual tipo de cartão deve ser criado, além de detalhes a serem exibidos no cartão, como o valor de um vale-presente ou o nome de um titular.
A API Google Wallet oferece um conjunto predefinido de classes e objetos de cartão que você cria instâncias para gerar um cartão emitido para um usuário, como GiftCardClass e GiftCardObject, GenericClass e GenericObject, entre outros.
Cada instância de objeto de cartões e classe de cartões é definida como um objeto JSON, que tem um conjunto de propriedades obrigatórias e opcionais que correspondem ao caso de uso específico destinado ao tipo de cartão.
Classes de cartões
Pense em uma classe de cartões como um modelo compartilhado usado para criar um ou mais cartões que você emitirá para os usuários. Uma classe de cartões define um conjunto comum de propriedades que serão incluídas em todos os cartões que se referem a ele.
Por exemplo, a instância a seguir de EventTicketClass define os campos comuns a todos os ingressos emitidos para um próximo evento(local, nome do evento, emissor, data/hora).
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"eventName": {
"defaultValue": {
"language": "en-US",
"value": "Google Live"
}
},
"venue": {
"name": {
"defaultValue": {
"language": "en-US",
"value": "Shoreline Amphitheater"
}
},
"address": {
"defaultValue": {
"language": "en-US",
"value": "ADDRESS_OF_THE_VENUE"
}
}
},
"dateTime": {
"start": "2023-04-12T11:30"
},
"reviewStatus": "UNDER_REVIEW"
}
Cada instância de uma classe de cartões requer uma propriedade id, que você especifica. Esse ID de classe
funciona como um identificador exclusivo que você vai referenciar sempre que for usado para criar uma nova instância de objeto de
cartões.
Objetos de cartões
Enquanto uma instância de uma classe de cartões especifica um conjunto de propriedades compartilhadas a serem usadas em um ou mais cartões, um objeto de cartões especifica os detalhes exclusivos de um cartão específico emitido para um usuário específico.
Por exemplo, quando um cartão de ingresso de evento é criado com a API Google Wallet, uma instância de EventTicketObject
inclui propriedades para o assento atribuído a esse ingresso, já que esses valores serão exclusivos para cada
ingresso emitido.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Cada instância de um objeto de cartões requer uma propriedade id, que você especifica. Esse ID de objeto
atua como um identificador exclusivo ao qual você fará referência ao emitir o cartão para um usuário.
Como as classes de cartões funcionam com objetos de cartões
Os objetos de cartões precisam estender uma instância de uma classe de cartões referenciando o ID da classe ou incluindo a definição completa da classe de cartões. Essa relação entre uma classe de cartões e uma instância de objeto de cartões significa que é possível definir e atualizar propriedades comuns a todos os cartões emitidos por meio da instância da classe de cartões e propriedades exclusivas a um cartão individual na instância do objeto de cartões.
Por exemplo, o diagrama a seguir de um cartão de ingresso de evento simples mostra como os campos definidos no EventTicketClass compartilhado e os campos de um ingresso específico definido no EventTicketObject são combinados para construir o cartão emitido final. Observe como o ID da classe de cartões é referenciado na propriedade classId do objeto de cartões.
As alterações feitas em uma instância de classe de cartões serão propagadas imediatamente em todas as instâncias de objetos de cartões que se referem a ela. Os usuários verão todas as alterações feitas em uma instância de classe de cartões refletidas no cartão no app Carteira do Google na próxima sincronização.
Adicionar um cartão à Carteira do Google de um usuário
Para adicionar um cartão à Carteira do Google de um usuário, crie um JSON Web Token (JWT) contendo declarações que você (o emissor) está fazendo sobre a instância do objeto de cartões que será salva na Carteira do Google do usuário, principalmente o ID do objeto da instância do objeto de cartões que você está emitindo para o usuário. Em seguida, o JWT é entregue ao usuário pelo botão Adicionar à Carteira do Google ou pelo link Adicionar à Carteira do Google.
Depois que um usuário clica no botão ou link para adicionar um cartão emitido à Carteira do Google, um link da instância do objeto de cartões codificada no JWT é vinculado à Conta do Google desse usuário. Isso significa que, quando o usuário clicar no botão novamente, já vai existir um link para esse objeto de cartões. Portanto, cópias duplicadas não serão adicionadas à carteira do usuário.
Se um usuário remover um cartão do app Carteira do Google, a instância do objeto de cartões correspondente será automaticamente desvinculada do usuário, mas não será excluída. Isso significa que um usuário pode clicar no botão Adicionar à Carteira do Google ou no link novamente para salvar o cartão sem a necessidade de criar um novo JWT ou instância de objeto de cartões.