Fluxos típicos da API

O diagrama a seguir ilustra um fluxo de comunicação típico usado para inserir uma classe, salvar um objeto e atualizar um objeto. Todas as ações entre o servidor, o navegador da Web e a API Google Pay for Passes são de sua responsabilidade. O diagrama a seguir usa Fidelidade como exemplo, mas todos os outros cartões podem usar um fluxo semelhante.

Figura 1. Diagrama de fluxo da API.

Fluxo de API típico para botões JS e links da Web JWT

A descrição a seguir explica o mesmo processo da figura 1 em mais detalhes. Ela abrange o fluxo típico da API para botões JavaScript (JS) e JSON Web Tokens (JWTs):

1. O emissor do cartão de fidelidade cria uma LoyaltyClass.
1. Seu servidor define a LoyaltyClass.
2. Seu servidor faz uma solicitação POST para inserir a LoyaltyClass no servidor da API Google Pay for Passes.
Observação: se você usar o botão JS, esta etapa pode não ser necessária. Como não há limite de caracteres, você não precisa inserir a classe antes. No entanto, ainda é preferível pré-inserir uma classe para que ela possa ser usada várias vezes. Geralmente, esse é o melhor método para processar cartões de fidelidade.
2. Seu servidor tem um serviço que gera um JWT para um LoyaltyObject de uma determinada LoyaltyClass. Esse objeto representa o cartão de fidelidade do usuário.
1. Seu servidor usa um JWT para renderizar um botão Salvar no Google Pay (S2GP):
• Para sites, use nosso botão JavaScript.
• Para e-mails, SMS e apps, use o link JWT com um botão S2GP.
3. O usuário clica ou toca em Salvar no Google Pay no e-mail, app, SMS ou site do emissor do cartão de fidelidade.
1. O usuário é direcionado a uma página de destino para salvar um objeto LoyaltyClass. O objeto a ser salvo é renderizado na página de destino com base no JWT. Se o usuário tocar no botão em um app, ele será solicitado a salvar o objeto no app Google Pay.
2. O usuário clica em Salvar no Google Pay na propriedade do emissor para salvar o LoyaltyObject.
3. O LoyaltyObject é inserido no servidor do Google e enviado ao app Google Pay. O LoyaltyObject é nomeado como "Cartão de fidelidade".
Observação: após o usuário salvar o cartão ou um servidor REST inserir uma LoyaltyClass ou um LoyaltyObject pela primeira vez, os JWTs subsequentes com o mesmo classID ou objectID vão renderizar o que já está definido no servidor do Google. Se você alterar as informações no JWT de um classID ou objectID existente, ele não atualizará os dados. Veja a Etapa 4 para saber como atualizar classes e objetos existentes.
4. O emissor atualiza os dados do cartão:
1. O emissor do cartão de fidelidade faz uma solicitação GET do LoyaltyObject com o uso do Object.id.
2. O emissor do cartão de fidelidade atualiza o LoyaltyObject.
3. O emissor do cartão de fidelidade faz uma solicitação PUT ou PATCH para inserir o LoyaltyObject atualizado no servidor da API Google Pay for Passes.
4. O LoyaltyObject é enviado para o app Google Pay.

Variação JWT "skinny"

Devido ao truncamento dos navegadores, os JWTs usados em links da Web não devem exceder 1.800 caracteres. Se isso se tornar um problema, talvez seja melhor inserir a classe e o objeto antes. Assim, o JWT precisará conter apenas o campo ID do objeto.

Observação: insira a classe e o objeto somente depois que um usuário mostrar que quer salvar um cartão no Google Pay. Para iniciar o fluxo de salvamento JWT dinâmico, recomendamos que você defina seu próprio link para salvar.

O diagrama a seguir mostra um fluxo de API para adicionar o botão Salvar no Google Pay ao seu e-mail ou SMS.

Figura 2. Diagrama JWT dinâmico.

Fluxo da API de solicitação POST do JWT

Geralmente, é difícil implementar o trabalho de back-end necessário para criar e inserir uma classe antes que um objeto seja salvo, mas é provável que os JWTs excedam o limite de 1.800 caracteres. Isso é mais útil para ingressos de eventos e cartões de embarque, em que muitas classes são criadas ao longo do tempo.

Observação: o método de solicitação POST do JWT pode ser usado quando você salva pelo app, mas não é uma alternativa para SMS ou e-mail, porque utiliza uma chamada POST.

Veja o fluxo a seguir, que usa como exemplo uma classe de voo:

1. Seu servidor gera um JWT para FlightObject e FlightClass. Ambos são definidos no JSON, e o FlightObject referencia a FlightClass.
2. Esse JWT é enviado do seu servidor para o aplicativo cliente, que exibe um botão Salvar no Google Pay. Use um botão que siga as diretrizes da marca S2GP.
3. O usuário clica no botão S2GP em seu aplicativo cliente.
   1. Uma solicitação POST é feita no terminal JWT. Isso insere o ID da classe e o ID do objeto. Se o(s) ID(s) de classe ou de objeto no JWT já existirem no sistema, eles não serão inseridos novamente. Revise nossa documentação de referência da API sobre como atualizar classes e objetos existentes. Se eles já tiverem sido inseridos, nenhum erro será lançado.
   2. A resposta de URI retornada é aberta para o usuário para que ele possa salvar o cartão. Esse URI é válido por uma semana após ser retornado.

Para implementar a API, leia Usar o método de solicitação POST do JWT.

Figura 3. Diagrama de solicitação POST do JWT.

Na figura 3, não há setas entre "Seu servidor" e "Servidor do Google" no fluxo de salvamento. Essa é a diferença fundamental entre uma POST do JWT e o método de link e intent do JWT. No entanto, recomendamos que você implemente a comunicação de servidor para servidor para atualizar os cartões.