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ão e um objeto de cartão. Sempre que você emitir um cartão para um usuário, vai precisar de uma instância de uma classe e um objeto de cartão. Isso informa à API Google Wallet qual tipo de cartão criar, além de detalhes para mostrar nele, como o valor de um vale-presente ou o nome de um portador de ingresso.
A API Google Wallet oferece um conjunto predefinido de classes e objetos de cartão que você cria instâncias e usa para criar um cartão emitido para um usuário, como GiftCardClass e GiftCardObject, GenericClass e GenericObject, entre outros.
Cada instância de classe e objeto de cartão é definida como um objeto JSON, que tem um conjunto de propriedades obrigatórias e opcionais que correspondem ao caso de uso específico pretendido para esse tipo de cartão.
Classes de cartões
Pense em uma classe de cartão como um modelo compartilhado usado para criar um ou mais cartões que você vai emitir para seus usuários. Uma classe de cartão define um conjunto comum de propriedades que serão incluídas em todos os cartões que a referenciam.
Por exemplo, a instância a seguir de EventTicketClass define os campos comuns a todos os ingressos emitidos para um evento futuro(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ão exige uma propriedade id, que você especifica. Esse ID de classe
funciona como um identificador exclusivo que você vai referenciar sempre que o usar para criar uma nova instância
do objeto de cartão.
Objetos de cartão
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 para evento é criado com a API Google Wallet, uma instância EventTicketObject
inclui propriedades para o assento atribuído a esse ingresso, já que esses valores sã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ão exige uma propriedade id, que você especifica. Esse ID do objeto
funciona como um identificador exclusivo que você vai referenciar ao emitir o cartão para um usuário.
Como as classes de cartão funcionam com os objetos de cartão
Os objetos de cartão precisam estender uma instância de uma classe de cartão referenciando o ID da classe ou incluindo a definição completa da classe de cartão. Essa relação entre uma classe de cartões e uma instância de objeto de cartões significa que você pode definir e atualizar propriedades comuns a todos os cartões emitidos pela instância da classe de cartões e propriedades exclusivas de um cartão individual na instância do objeto de cartões.
Por exemplo, o diagrama a seguir de um cartão de ingresso simples mostra como os campos definidos no EventTicketClass compartilhado e os campos de um ingresso específico definidos no EventTicketObject se combinam 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 mudanças feitas em uma instância da classe de cartões são propagadas imediatamente em todas as instâncias do objeto de cartões que fazem referência a ela. Os usuários vão ver as mudanças feitas em uma instância da classe Passes refletidas no cartão do app Carteira do Google na próxima vez que fizerem a sincronização.
Como 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) que contenha 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. O mais importante é o ID do objeto da instância do objeto de cartões que você está emitindo para o usuário. O JWT é entregue ao usuário por um botão Adicionar à Carteira do Google ou um 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 para a 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ão, então 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ão correspondente será desvinculada automaticamente do usuário, mas não será excluída. Isso significa que o usuário pode clicar novamente no botão ou link Adicionar à Carteira do Google para salvar o cartão sem precisar de uma nova instância do objeto de cartões ou de um JWT.