Casos de uso

Este guia descreve formas específicas de usar a API Google Pay for Passes para interagir com seus clientes na vertical de cartões de embarque para voos. A API permite oferecer as seguintes opções aos seus clientes:

Atualizar cartões de embarque

Se um cartão de embarque for alterado depois de salvo, será possível usar UPDATE ou PATCH na API REST para informar essas alterações aos passageiros.

Para atualizar os campos de todos os cartões de embarque de um voo específico, como quando o horário de partida previsto é alterado, basta aplicar UPDATE ou PATCH a FlightClass. O Google propaga essas informações para o FlightObject salvo no app Google Pay, que é então associado à FlightClass atualizada.

Para atualizar um único cartão de embarque, por exemplo, quando o número do assento de um passageiro é alterado, é necessário aplicar UPDATE ou PATCH a um único FlightObject. O Google propaga essas informações para o FlightObject desse passageiro, que é salvo no app Google Pay.

Às vezes, talvez você não saiba quando ocorre uma alteração ou quando acionar uma chamada API REST UPDATE ou PATCH. Nesse caso, agende periodicamente as chamadas API REST UPDATE ou PATCH para cada FlightClass, bem como para cada FlightObject.

Fontes de dados para atualizações de voo

Se a hora fornecida por class.localScheduledDepartureDateTime estiver entre as últimas 24 horas ou as próximas 48 horas, um cartão de status de voo será exibido para os usuários. Quando isso acontece, o Google Pay pode exibir dados do Google Flights ou das informações fornecidas no cartão do Google Pay. A fonte a ser usada depende do seguinte:

  • Se a class.localEstimatedOrActualDepartureDateTime não for fornecida, o Google Flights será usado. Nesse caso, qualquer class.flightStatus que você definir será ignorado.

    Por exemplo, se um voo estiver atrasado, os usuários verão um cartão na guia "Página inicial" do aplicativo do Google Pay que exibirá o novo horário de partida. Um cartão de atraso semelhante também será exibido para os usuários na guia "Cartões".

  • Se você forneceu o class.localEstimatedOrActualDepartureDateTime, mas não o class.flightStatus, o horário fornecido será usado para determinar se um voo está atrasado. O status do voo no cartão é exibido aos usuários com base na seguinte lógica:
    • Se class.localEstimatedOrActualDepartureDateTime for maior que class.localScheduledDepartureDateTime, os usuários veem no cartão o voo listado como atrasado.
    • Se class.localEstimatedOrActualDepartureDateTime não for maior que class.localScheduledDepartureDateTime, os usuários veem as informações de voo no cartão, mas sem nenhuma mensagem de status.

Se você não quiser usar o Google Flights como fonte de informações sobre voos, forneça o flightStatus, o localScheduledDepartureDateTime e o localEstimatedOrActualDepartureDateTime de uma FlightClass. Somente seus dados serão usados no cartão. Como alternativa, se você usar um código de transportadora ICAO em vez de um código IATA na FlightClass, o Google Voos não será usado como fonte de informações de voo.

Quando determinados campos são alterados, o usuário recebe notificações push sobre as alterações. Para mais detalhes, consulte Receber notificações de atualização de voo.

Salvar uma jornada de voo com vários trechos

É comum que uma jornada de voo inclua vários trechos, em vez de ser uma viagem direta para o destino de uma pessoa. Durante essa jornada, as companhias aéreas emitem um cartão de embarque por trecho da viagem. A API Google Pay for Passes imita esse comportamento, com um FlightObject por trecho.

Isso significa que, se houver dois passageiros voando de SFO para LAX e, depois, para TPE, haverá duas estruturas FlightClass e quatro objetos FlightObject:

  FlightClass A (SFO para LAX: companhia aérea, número do voo, hora de partida) FlightClass B (LAX para TPE: companhia aérea, número do voo, hora de partida)
Passageiro Q FlightObject: id_01 FlightObject: id_02
Passageiro Z FlightObject: id_03 FlightObject: id_04

Esses campos refletem os cartões de embarque físicos. Os passageiros Q e Z teriam dois cartões de embarque impressos.

Fazer um botão para salvar vários cartões

Para usuários que compram vários cartões e querem salvar todos eles no Google Pay, é útil que eles possam salvar muitos objetos com um clique do botão ou link Salvar no Google Pay. Vários objetos ou classes podem ser definidos no JSON Web Token (JWT) a ser assinado.

O JWT deve ser feito em um dos seguintes formatos:

  • Usando apenas classes e objetos pré-inseridos.
  • Usando somente recursos de objeto e classe que são totalmente definidos dentro do JWT.

Para ver um exemplo de como criar um botão para vários cartões, consulte o botão Salvar vários passageiros. Para mais informações sobre a representação da interface do usuário de cartões, consulte Agrupar vários cartões de embarque.

Agrupar vários cartões de embarque

Há recursos que funcionarão de maneira diferente se forem usados em um grupo, em vez de objetos individuais, como notificações de status ou organização de vários cartões salvos para muitos passageiros na interface do usuário.

Os objetos FlightObject só serão considerados um grupo se todas as propriedades a seguir forem as mesmas em cada objeto:

  • Código do emissor (da API Google Pay for Passes Merchant Center)
  • class.flightHeader.carrier.carrierIataCode
  • class.flightHeader.flightNumber
  • class.localScheduledDepartureDateTime
  • object.reservationInfo.confirmationCode

Se dois objetos FlightObject forem diferentes em qualquer uma das propriedades acima, eles não serão considerados como agrupados.

Gerenciar cartões expirados

Na guia "Cartões" do aplicativo do Google Pay, há uma seção "Cartões expirados" que contém todos os cartões arquivados ou inativos. Um cartão de embarque será movido para a seção "Cartões expirados" se pelo menos uma das seguintes condições for verdadeira:

  • Passaram-se 24 horas desde class.localScheduledDepartureDateTime ou class.localEstimatedOrActualDepartureDateTime do cartão de embarque. O cartão será movido para "Cartões expirados" a qualquer momento entre 24 e 48 horas após class.localScheduledDepartureDateTime ou class.localEstimatedOrActualDepartureDateTime.
  • O object.validTimeInterval.end.date do cartão de embarque terminou. O cartão pode passar para "Cartões expirados" a qualquer momento em até 24 horas após object.validTimeInterval.end.date.
  • O campo state do FlightObject está marcado como Expired, Inactive ou Completed.

Receber notificações sobre próximos voos

O Google Pay envia uma notificação ao usuário três horas antes do horário de partida do voo. O horário de partida do voo é estabelecido por class.localScheduledDepartureDateTime.

Para receber essa notificação, o usuário precisa ativar as notificações. Para isso, é preciso navegar para Configurações > Notificações e ativar Atualizações sobre seus cartões.

A notificação é mostrada em dois lugares: na tela de bloqueio e na área de notificações.

Tela de bloqueio

Se o usuário tiver notificações ativadas na tela de bloqueio, ele receberá a notificação de status no seguinte formato não modificável:

Boarding pass for your flight to class.destination.airportIataCode
Expand for more options

Se ele tocar na notificação e desbloquear o dispositivo, o cartão será exibido no app Google Pay.

Se o usuário tiver vários cartões, somente será mostrado o próximo que poderá ser utilizado. Se ele salvou vários cartões de embarque para o mesmo trecho de voo, conforme Agrupar vários cartões de embarque, a notificação mostra apenas um dos cartões do grupo. No entanto, o usuário pode deslizar para a esquerda e para a direita depois de tocar na notificação para ver os outros cartões nesse grupo.

As notificações de status não serão descartadas automaticamente depois que um usuário as abrir. A dispensa automática ocorrerá 60 minutos depois do horário de partida programado.

Área de notificações

A notificação mostra o código de barras e outras opções. O usuário pode tocar nele para ver o cartão no app Google Pay.

A notificação é fixada na área de notificações. Ela não será descartada automaticamente depois que um usuário a abrir. A dispensa automática ocorrerá 60 minutos depois do horário de partida programado.

Receber notificações de atualização de voos

Quando determinados campos de um voo são alterados, os usuários com um ou mais cartões de embarque salvos recebem uma notificação push no dispositivo. Isso acontece somente se condições específicas forem atendidas.

Terminal de origem e portão

Se você alterar class.origin.terminal ou class.origin.gate e a condição a seguir for atendida, uma notificação será enviada informando que o campo foi alterado.

  • O intervalo até class.localScheduledDepartureDateTime é de menos de três horas.

A notificação é exibida no seguinte formato: "A companhia aérea X atualizou o portão para A1". Não é possível alterar o formato.

Horário de embarque e de partida

Se você alterar class.localBoardingDateTime ou class.localEstimatedOrActualDepartureDateTime e as condições abaixo forem atendidas, uma notificação será enviada informando que o campo foi alterado.

  • O intervalo até class.localScheduledDepartureDateTime é de menos de 24 horas.
  • O horário em questão é alterado em pelo menos 10 minutos.

A notificação é exibida no seguinte formato: "A companhia aérea X atualizou o horário de embarque para 18:00." Não é possível alterar o formato.

Depois que o usuário salvar um cartão, faça referência ao atributo objectId dele para definir um direcionamento para o cartão.

Use o link a seguir para fazer referência ao cartão:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

O cartão pode ser exibido no app Google Pay ou em um navegador da Web.