Neste documento, listamos terminologia e conceitos comuns que você precisa conhecer ao usar a API Google Wallet.
Passes
Aprovado
Um cartão é uma instância de um objeto de cartões emitido para um usuário salvar na Carteira do Google. A API Google Wallet oferece suporte a vários tipos de cartão comuns, incluindo cartões de embarque, ingressos de eventos, carteiras de identidade e muito mais. A API Google Wallet também oferece um tipo de cartão genérico que pode ser usado para criar cartões que não têm suporte específico de outra forma.
Na maioria dos casos, um cartão é criado usando uma classe e um objeto de cartões.
Emissor de cartão
Um emissor de cartão é uma entidade que cria cartões e os emite para os usuários salvarem na Carteira do Google. O emissor do cartão é o proprietário dos cartões e pode criá-los, emiti-los e atualizá-los. Os emissores de cartões podem ser desenvolvedores individuais, empresas e organizações, bem como agregadores que criam e emitem cartões em nome de terceiros, como uma empresa especializada em implementar ingressos para eventos ou cupons para varejistas.
Classe de cartões
Uma classe de cartões pode ser considerada um modelo compartilhado de criação dos cartões. Uma classe de cartões define determinadas propriedades que serão incluídas em todos os cartões que a usam. Um emissor de cartão pode criar várias classes, cada uma com o próprio conjunto distinto de propriedades que definem atributos como estilo e aparência, além de recursos adicionais como Toque inteligente e inscrição e login.
Na maioria dos casos, um cartão é criado fornecendo uma classe de cartões para definir o modelo do cartão e um objeto de cartões para definir as especificidades do cartão individual que está sendo emitido.
Objeto de cartões
Um objeto de cartões define um cartão individual emitido para um usuário salvar na Carteira do Google. Os objetos de cartões geralmente contêm informações específicas do usuário. Por exemplo, embora uma classe de cartões possa definir como será um cartão de vale-presente de uma loja específica, o objeto de cartões fornecerá detalhes específicos, como o saldo ou a data de validade.
Um objeto de cartões precisa ser criado para cada cartão emitido, diferente das classes de cartões, que podem ser compartilhadas em várias instâncias de cartão.
Cartões pessoais
Alguns cartões criados com a API Google Wallet podem conter dados sensíveis do usuário. Eles exigem mais proteção para manter os dados dos usuários seguros e são gerenciados de forma diferente na API Google Wallet usando o tipo de cartão pessoal genérico. O cartão pessoal genérico precisa ser usado nos casos em que dados sensíveis (conforme definido na Política de Uso aceitável da API Google Wallet) são incluídos no cartão e podem estar sujeitos a outros controles de privacidade e à análise durante a integração.
Toque inteligente
O Toque inteligente é um protocolo de comunicação a curta distância do Google para transmitir dados entre um dispositivo móvel e um terminal NFC. Com a tecnologia do Toque inteligente, os usuários podem segurar o smartphone próximo a qualquer terminal NFC compatível para resgatar cartões salvos na Carteira do Google.
Para usar o protocolo de Toque inteligente com seus cartões, você precisa estabelecer uma relação com um provedor de terminais compatíveis com o Toque inteligente.
APIs e SDK
API Google Wallet
A API Google Wallet é um serviço fornecido pelo Google que permite criar e emitir cartões para os usuários salvarem na Carteira do Google. Ela pode ser usada de várias maneiras diferentes, incluindo a API REST da Carteira do Google, o SDK da Carteira do Google para Android e o console da Carteira do Google.
API REST da Carteira do Google
A API REST da Carteira do Google é uma interface para criar e gerenciar cartões de maneira programática enviando solicitações HTTP para a API.
Para usar a API REST da Carteira do Google, você também vai precisar de uma conta do Google Cloud para criar uma conta de serviço, que será usada para autenticar solicitações para a API REST da Carteira do Google.
SDK da Carteira do Google para Android
O SDK da Carteira do Google para Android oferece um conjunto de métodos práticos para trabalhar com a API Google Wallet nos seus apps Android, como criar e emitir cartões.
Adicionar à Carteira do Google
"Adicionar à Carteira do Google" botão
"Adicionar à Carteira do Google" é um recurso aprovado pelo Google para apresentar um cartão a um usuário. Quando um usuário clica ou toca no botão, a opção "Adicionar à Carteira do Google" deve ser acionado para iniciar o fluxo de adição do cartão emitido à Carteira do Google do usuário.
Recomendamos usar a opção "Adicionar à Carteira do Google" sempre que possível, porque se trata de um elemento de interface familiar com o qual os usuários já sabem como interagir.
Os recursos e as diretrizes de uso do botão estão disponíveis nas Diretrizes de marca da API Google Wallet.
"Adicionar à Carteira do Google" link
Com uma opção "Adicionar à Carteira do Google" , você pode emitir um cartão para um usuário com um hiperlink normal. Você pode usá-lo sempre que puder usar hiperlinks, como e-mails, SMS, sites e apps para dispositivos móveis.
"Adicionar à Carteira do Google" Para criar links, anexe um JWT assinado ao URL https://pay.google.com/gp/v/save/.
Conta do emissor
Modo de demonstração
Quando você cria sua conta de emissor, ela fica no "modo de demonstração" até que o acesso de publicação seja aprovado. No modo de demonstração, é possível criar cartões, mas eles só podem ser emitidos para usuários com a função "Administrador" ou "Desenvolvedor" funções da sua conta de emissor ou de usuários que foram adicionados como contas de teste no console da Carteira do Google.
No "Modo de Demonstração", o título dos passes emitidos começará automaticamente com as palavras "[SOMENTE TESTE]". para indicar que ele é aprovado somente para fins de teste.
Contas de teste
Quando sua conta de emissor estiver no "Modo de demonstração", se você quiser emitir cartões para usuários que não tenham o papel "Administrador" ou "Desenvolvedor" para sua conta, é preciso adicioná-las como contas de teste no console da Carteira do Google. Os usuários inscritos como contas de teste vão poder adicionar cartões emitidos por você à Carteira do Google. Isso é útil para testar seus cartões com um público mais amplo no "modo de demonstração".
Perfil da Empresa
Para criar uma conta de emissor para a API Google Wallet, configure um Perfil da Empresa ao se registrar no programa Google Pay e Console da Carteira. O Perfil da Empresa fornece ao Google informações básicas sobre sua empresa ou organização e precisa ser aprovado para acesso de publicação.
Acesso de publicação
Antes de emitir cartões que os usuários possam salvar na Carteira do Google, você precisa receber aprovação para o acesso de publicação. Para ter o acesso de publicação aprovado, você precisa ter criado pelo menos uma classe de cartões e um Perfil da Empresa completo. Os emissores que querem emitir cartões usando o SDK da Carteira do Google para Android também precisam enviar a impressão digital SHA-1 do app.
Para solicitar acesso de publicação, acesse o console da Carteira do Google e clique no botão "Solicitar acesso de publicação" . A equipe da Carteira do Google analisará sua solicitação e notificará você quando o acesso de publicação for concedido.
Autenticação
JSON Web Token (JWT)
JSON Web Tokens são um padrão do setor comumente usado para transferir informações com segurança como um objeto JSON. Ao usar a API Google Wallet, você codifica os detalhes do objeto de cartões que quer usar para criar uma instância de cartão no formato JWT (pronunciado, "jot") e envia esse JWT em uma solicitação para a API Google Wallet.
Para garantir a segurança, os JWTs são assinados com uma senha secreta antes de serem enviados à API Google Wallet. Se você estiver usando a API REST da Carteira do Google, a chave secreta de assinatura será sua chave da conta de serviço do Google Cloud. Se você usa o SDK da Carteira do Google para Android, a chave secreta de assinatura é a impressão digital SHA-1 do seu app Android.
Conta de serviço
Uma conta de serviço do Google Cloud é um tipo especial de conta, geralmente usado por um aplicativo ou carga de trabalho de computação, e não por uma pessoa. No caso da API Google Wallet, uma conta de serviço é o que você vai usar para autenticar as solicitações enviadas à API REST da Google Wallet.
As contas de serviço são criadas no console do Google Cloud. Para usar uma conta de serviço, você também precisa ativar a API Google Wallet no console do Cloud para permitir que a conta de serviço faça solicitações à API REST da Carteira do Google.
Chave da conta de serviço
Uma chave da conta de serviço é a credencial que você vai usar para autenticar chamadas para a API REST da Carteira do Google. A chave da conta de serviço é considerada altamente confidencial e precisa ser mantida em sigilo, porque concede acesso a muitos dos recursos do emissor de cartão da sua conta usando a API REST da Carteira do Google, incluindo a criação de classes e objetos de cartões.
Impressão digital SHA-1
A impressão digital SHA-1 do seu certificado de assinatura de apps Android é a credencial que você vai usar para autenticar chamadas para a API Google Wallet ao usar o SDK da Carteira do Google para Android. A impressão digital SHA-1 do seu certificado é gerada usando o Gradle ou o keytool. Para usar a impressão digital para autenticar suas solicitações, é necessário registrá-la no console da Carteira do Google.