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, vai precisar de uma instância de uma classe de cartões e de um objeto de cartões, que informa à API Google Wallet o tipo de cartão a ser criado, bem como os detalhes a serem exibidos no cartão, como o valor de um vale-presente ou o nome do titular do cartão.
A API Google Wallet oferece um conjunto predefinido de classes e objetos de cartões usados por você para criar instâncias e um cartão emitido para um usuário, como GiftCardClass, GiftCardObject, GenericClass, GenericObject e outros.
Cada instância de classe e objeto 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 pretendido para esse 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 seus usuários. Uma classe de cartões define um conjunto comum de propriedades que serão incluídas em todos os cartões que fazem referência a ela.
Por exemplo, a seguinte instância do 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. Este ID de classe
atua como um identificador exclusivo que você vai referenciar sempre que o usar para criar um novo objeto de cartões
instância.
Objetos de cartões
Enquanto uma instância de uma classe de cartões especifica um conjunto de propriedades compartilhadas a serem usadas em uma ou mais 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, um EventTicketObject
inclui as propriedades do assento atribuído àquele ingresso, já que esses valores serão exclusivos a cada
tíquete 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. Este ID de objeto
funciona como um identificador exclusivo que você vai referenciar 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 fazendo referência ao ID de 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 pela instância da classe de cartões, e propriedades exclusivas para 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 definidos no EventTicketObject se combinam para criar o cartão final emitido. 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 serão propagadas imediatamente para todas as instâncias do objeto de cartões que o referenciam. Os usuários verão todas as alterações feitas em uma instância da 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) que contenha reivindicações. você (o emissor) está fazendo sobre a instância do objeto de cartões que será salva na Carteira do Google do usuário: 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 pelo botão Adicionar à Carteira do Google ou um botão Adicionar à Carteira do Google .
Depois que um usuário clicar 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 é vinculada à Conta do Google desse usuário. Isso significa que quando o usuário clicar no botão novamente, já existirá um link para esse objeto de cartões. Portanto, cópias 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 de objeto de cartões correspondente será automaticamente desvinculado do usuário, mas não é excluído. Isso significa que um usuário pode clicar Botão ou link Adicionar à Carteira do Google novamente para salvar o cartão sem a necessidade de nova instância de objeto de cartões ou JWT a ser criado.