Pases vinculados automáticamente

Segundo plano

La función Pases vinculados automáticamente te permite enviar pases adicionales a un usuario que ya tiene tu pase existente en su Billetera de Google. También puedes vincular previamente los pases a un pase principal cuando un usuario guarda el pase principal. El pase vinculado automáticamente se agrupa con el pase principal con un texto destacado sobre este que le informa al usuario que se vinculó un pase nuevo. Los siguientes tipos de pases son compatibles como pases principales o vinculados:

  • Entrada del evento
  • Tarjeta de embarque
  • Pase de transporte público
  • Oferta
  • Tarjeta de regalo
  • Pase de lealtad
  • Pase genérico
Ejemplo principal de pase vinculado automático Ejemplo secundario de pase vinculado automático
Pase principal con el texto destacado que indica que se agregó un pase nuevo Nuevo pase vinculado al pase principal

Casos de uso

Es posible que tengas diferentes casos de uso para vincular pases a uno existente. A continuación, se muestran algunos ejemplos:

  • Vincula una oferta a una tarjeta de lealtad existente.
  • Vincula un cupón de comida a una tarjeta de embarque o una entrada para un evento.
  • Vincula un pase de estacionamiento a una entrada para un evento.

Algunas consideraciones cuando se usan pases vinculados automáticamente

  • El objeto principal y el objeto vinculado deben usar el mismo issuerId.
  • Existe un límite de 50 objetos vinculados por objeto principal.
  • No se garantiza que se envíen pases vinculados automáticamente y se considera un esfuerzo máximo. Los usuarios pueden inhabilitar la recepción de pases vinculados automáticamente. Si el caso de uso es crítico y el usuario debe recibir el pase vinculado, te recomendamos que te comuniques por medio de otro canal para asegurarte de que lo agregue.
  • Las actualizaciones de la AUP de la Billetera de Google incluyen orientación sobre el uso de los Pases vinculados automáticamente que se deben cumplir.

Pasos para la integración

Si ya creaste un objeto principal, puedes omitir el paso 1.

  1. Crea un objeto de cualquier tipo de pase que se enumere con los parámetros requeridos. Este es el objeto principal.
  2. Crea otro objeto de cualquier tipo de pase de la lista. Este será el objeto vinculado.
  3. Antes o después de guardar el objeto principal, actualiza el objeto principal con el ID del objeto vinculado en el parámetro linkedObjectIds.

Se requiere una carga útil mínima para establecer los linkedObjectIds en un pase principal. Entre los 3 parámetros obligatorios, se incluyen los siguientes:

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. ISSUERID.LINKED_OBJECT_ID

Ejemplo de solicitud JSON para agregar un objeto vinculado a un objeto pase

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
  }
  …

Ejemplo de respuesta JSON después de vincular un objeto a un objeto de pase

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

Comportamiento esperado

Después de recibir una respuesta correcta, los dispositivos con el pase que actualizaste deberían recibir el pase vinculado. Este pase vinculado se agrupará con el pase principal. Los usuarios pueden ver el pase vinculado deslizando el dedo hacia la derecha.

Manejo de excepciones

Es posible que se produzcan errores potenciales con el uso incorrecto de la API, que pueden incluir lo siguiente:

Mensaje Motivo
El objeto principal y el objeto vinculado no comparten el mismo ID de entidad emisora. No puedes adjuntar un objeto vinculado al objeto de otro emisor.
El objeto principal y el objeto vinculado se refieren al mismo objeto. No puedes adjuntar el mismo objeto que el linkedObject.
El objeto vinculado no existe. El objeto vinculado ya debería estar insertado en la API de Wallet.
El objeto vinculado ya tiene otro objeto vinculado. No se pueden agregar objetos vinculados anidados. Los objetos vinculados no pueden tener otro objeto vinculado.
El objeto ya está vinculado a otro. No se pueden agregar objetos vinculados anidados. El objeto principal no puede ser un objeto vinculado por sí solo.
No se pueden agregar más objetos vinculados porque se superó el límite. Se alcanzó el límite de 50 pases vinculados para el pase principal.