Informações gerais

Com a API Google Pay Passes, os parceiros podem especificar um endpoint para ativar um cartão de transporte público. Quando a ativação é necessária, o botão "Ativar" aparece para o usuário. Quando a pessoa toca nele, o endpoint especificado é chamado com os parâmetros descritos abaixo. O endpoint precisa garantir que o cartão tenha informações de resgate válidas (código de barras ou inspeção visual) antes de retornar. O cartão na Carteira do usuário será atualizado para exibir as informações de resgate. Antes da ativação, as informações de resgate não são exibidas.

API Activation

O endpoint de ativação é especificado na API usando activationOptions na classe de transporte público. O parceiro é responsável por manter um endpoint de ativação funcional com latência razoável.

  activationOptions: {
    activationUrl: string
  }
Campo Descrição
activationUrl

string

URL do endpoint do parceiro que seria chamado para solicitações de ativação. O URL precisa estar hospedado em HTTPS, e o robots.txt precisa permitir que o caminho do URL seja acessível por UserAgent:Google-Valuables.

O estado de ativação é armazenado no objeto usando o campo activationStatus. Os status válidos incluem NOT_ACTIVATED e ACTIVATED. O endpoint de ativação precisa atualizar o objeto com o status ACTIVATED, além de garantir que o objeto tenha informações de resgate válidas, como um código de barras ou parâmetros de inspeção visual. O campo deviceContext pode ser usado para fixar dispositivos.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Campo Descrição
activationStatus

enum (ActivationStatus)

Status de ativação para este objeto de transporte público. Esse status muda a representação do ingresso e permite que os usuários realizem ações. Por exemplo, um botão "Ativar" vai ser renderizado nos detalhes do cartão se ele estiver definido como NOT_ACTIVATED.

Os valores aceitos são:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Um contexto de dispositivo para associar ao objeto. Se este campo for definido, as informações de resgate vão ser retornadas apenas para o dispositivo especificado.
hasLinkedDevice

boolean

Se este objeto está atualmente vinculado a um único dispositivo.
DeviceContext
Campo Descrição
deviceToken

string

Se este campo for definido, as informações de resgate só serão retornadas para o dispositivo especificado depois da ativação do objeto. Ele não pode ser usado como um identificador estável para rastrear o dispositivo de um usuário. Ele pode mudar em diferentes cartões para o mesmo dispositivo ou até mesmo em diferentes ativações para o mesmo dispositivo. Ao definir este campo, os autores das chamadas também precisam definir hasLinkedDevice no objeto que está sendo ativado.

O deviceToken é recebido do campo deviceContext de parâmetros de ativação.

Fixação no dispositivo

Com esse recurso, o usuário pode ativar o cartão e ver as informações de resgate apenas em um dispositivo. Como isso é separado de multipleDevicesAndHoldersAllowedStatus de ONE_USER_ONE_DEVICE, o cartão só aparece em um dispositivo. É recomendável usar o status ONE_USER_ALL_DEVICES com a fixação no dispositivo.

Antes da ativação, o usuário pode ver o cartão e o botão "Ativar" em todos os dispositivos dele. Depois de ativado e fixado, o dispositivo fixado exibirá informações de resgate, e outros dispositivos exibirão um botão "Ativar" para permitir que o usuário mova o cartão para outro dispositivo. Se você não quiser mover o cartão, mas a ativação em qualquer dispositivo for útil, ele poderá atualizar o cartão durante a ativação para ONE_USER_ONE_DEVICE em vez de usar a fixação no dispositivo.

Para implementar a fixação no dispositivo, o objeto precisa ser atualizado com o campo deviceToken, que é recebido com os parâmetros de ativação, além de definir hasLinkedDevice como verdadeiro na mesma chamada de API. É possível desvincular o cartão de um dispositivo definindo hasLinkedDevice como falso em uma chamada de API futura.

diagrama da sequência para fixação no dispositivo

Parâmetros de ativação

A solicitação para o endpoint de ativação vai conter os parâmetros a seguir.

Exemplo de JSON: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

Identificador Descrição
classId

ID de classe totalmente qualificado. Usa o seguinte formato:

<issuer_id.class_id>
objectIds

Matriz totalmente qualificada de IDs de objetos com o seguinte formato:

<issuer_id.object_id>
expTimeMillis Tempo de expiração em milissegundos desde época. Depois do tempo de expiração, a mensagem precisa ser considerada inválida.
eventType Sempre "activate".
nonce Valor de uso único para rastrear as entregas duplicadas.
deviceContext

Um ID exclusivo gerado pelo Google que representa o dispositivo em que o usuário está realizando ações. Esse ID precisa ser usado ao fazer atualizações que vinculam um objeto a um dispositivo.

Esse ID pode não ser constante nas solicitações futuras de um determinado dispositivo.