Contexto
Com o recurso de cartões vinculados automaticamente, é possível enviar outros cartões a um usuário que já tem o cartão na Carteira do Google. Você também pode a pré-vinculação é transmitida para um cartão principal quando um usuário salva o cartão principal (principal). O cartão vinculado automaticamente é agrupado com o cartão principal por um acima do cartão principal, informando ao usuário que um novo cartão foi vinculada. Os seguintes tipos de cartão são aceitos como cartões principais ou vinculados:
- Ingressos de evento
- Cartão de embarque
- Cartão de transporte público
- Oferta
- Vale-presente
- Cartão de fidelidade
- Cartão genérico
![]() |
![]() |
Cartão principal com a frase de destaque de que um novo cartão foi adicionado | Novo cartão vinculado ao cartão principal |
Casos de uso
Você pode ter diferentes casos de uso para vincular cartões a um cartão existente. Veja alguns exemplos:
- Vincular uma oferta a um cartão de fidelidade atual.
- Vincule um vale-refeição a um cartão de embarque ou ingresso de evento.
- Vincule um cartão de estacionamento a um ingresso de evento.
Algumas considerações ao usar os cartões vinculados automaticamente
- O objeto principal e o vinculado precisam usar o mesmo emissorId.
- Há um limite de 50 objetos vinculados por objeto principal.
- O envio automático de cartões vinculados não é garantido e considerado de todos os esforços possíveis. Os usuários podem desativar o recebimento de cartões vinculados automaticamente. Se o caso de uso for essenciais e o usuário deve receber o cartão vinculado, recomendamos comunicando-se por outro canal para garantir que o usuário adicione o cartão.
- Atualizações na Política de Uso Aceitável da Carteira do Google incluir orientações sobre o uso de cartões vinculados automaticamente que precisam ser respeitados.
Etapas de integração
Se você já criou um objeto principal, pule a etapa 1.
- Crie um objeto de qualquer tipo de cartão listado com os parâmetros necessários. Este é o objeto principal.
- Crie outro objeto de qualquer tipo de cartão listado. Este será o objeto vinculado.
- Antes ou depois de o objeto principal ser salvo, update o objeto principal com o ID do objeto vinculado em linkedObjectIds .
Há um payload mínimo necessário para definir os linkedObjectIds em um passar. Os três parâmetros obrigatórios incluem:
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- ISSUERID.LINKED_OBJECT_ID
Exemplo de solicitação JSON para adicionar um objeto vinculado a um objeto de cartão
… { "id": "ISSUERID.PASS_OBJECTID", "classId": "ISSUERID.PASS_CLASSID", "barcode": { "type": "qrCode", "value": "QR code" }, "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"} } …
Exemplo de resposta JSON depois de vincular um objeto a um objeto de cartão
… "state": "active", "linkedObjectIds": { "ISSUERID.LINKED_PASS_OBJECTID" } …
Comportamento esperado
Após receber uma resposta, os dispositivos com o cartão que você atualizou devem receber o cartão vinculado. Este cartão vinculado será agrupado com o cartão principal. Os usuários podem ver o cartão vinculado deslizando para a direita.
Como processar exceções
Possíveis erros podem acontecer com o uso incorreto da API, o que pode incluem
Mensagem | Motivo |
---|---|
O objeto principal e o objeto vinculado não compartilham o mesmo emissor ID. | Não é possível anexar um objeto vinculado ao objeto de outro emissor. |
O objeto principal e o objeto vinculado se referem ao mesmo objeto. | Não é possível anexar o mesmo objeto que o linkedObject. |
O objeto vinculado não existe. | O objeto vinculado já deve estar inserido na Carteira API. |
O objeto vinculado já tem outro objeto vinculado. Não é possível adicionar anúncios aninhados objetos vinculados. | Os objetos vinculados não podem ter outro objeto vinculado. |
O objeto já está vinculado a outro objeto. Não é possível adicionar links aninhados objetos. | O objeto principal não pode ser vinculado sozinho. |
Não é possível adicionar mais objetos vinculados. O limite foi excedido. | O limite de 50 cartões vinculados foi atingido na conta principal passar. |