Casi todos los pases que puedes emitir para que un usuario final los guarde en su Billetera de Google se definen con dos componentes: una clase Passes y un objeto Passes. Cada vez que emitas un pase a un usuario, necesitarás una instancia de una clase Passes y de un objeto Passes, que le indica a la API de la Billetera de Google qué tipo de pase se debe construir y también detalles que se deben mostrar en el pase, como el valor de una tarjeta de regalo o el nombre del titular de una entrada.
La API de la Billetera de Google proporciona un conjunto predefinido de clases Passes y Passes Objects que creas instancias y, luego, usas para crear un pase que se emite a un usuario, como GiftCardClass y GiftCardObject, GenericClass y GenericObject, entre otros.
Cada instancia de clase Passes y Passes Object se define como un objeto JSON, que tiene un conjunto de propiedades obligatorias y opcionales que corresponden al caso de uso específico destinado a ese tipo de pase.
Clases de aprobado
Piensa en una clase Passes como una plantilla compartida que se usa para crear uno o más pases que enviarás a tus usuarios. Una clase Passes define un conjunto común de propiedades que se incluirá en todos los pases que hagan referencia a él.
Por ejemplo, la siguiente instancia de EventTicketClass define los campos que son comunes a todas las entradas emitidas para un próximo evento(establecimiento, nombre del evento, entidad emisora, fecha y hora).
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"eventName": {
"defaultValue": {
"language": "en-US",
"value": "Google Live"
}
},
"venue": {
"name": {
"defaultValue": {
"language": "en-US",
"value": "Shoreline Amphitheater"
}
},
"address": {
"defaultValue": {
"language": "en-US",
"value": "ADDRESS_OF_THE_VENUE"
}
}
},
"dateTime": {
"start": "2023-04-12T11:30"
},
"reviewStatus": "UNDER_REVIEW"
}
Cada instancia de una clase Passes requiere una propiedad id, que debes especificar. Este ID de clase actúa como un identificador único al que harás referencia cada vez que lo uses para crear una instancia nueva de objeto Passes.
Pasa objetos
Mientras que una instancia de una clase Passes especifica un conjunto de propiedades compartidas para usar en uno o más pases, un objeto Passes especifica los detalles únicos de un pase específico que se emite a un usuario específico.
Por ejemplo, cuando se crea un pase de entrada para evento con la API de la Billetera de Google, una instancia de EventTicketObject incluye propiedades para el asiento asignado a ese boleto, ya que esos valores serán únicos para cada boleto emitido.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Cada instancia de un objeto Passes requiere una propiedad id, que debes especificar. Este ID de objeto actúa como un identificador único al que harás referencia cuando emitas el pase a un usuario.
Cómo funcionan las clases Passes con los objetos Passes
Los objetos Passes deben extender una instancia de una clase Passes haciendo referencia a su ID de clase o incluyendo la definición completa de la clase Passes. Esta relación entre una instancia de clase Passes y de objeto Passes implica que puedes configurar y actualizar las propiedades comunes a todos los pases emitidos a través de la instancia de la clase Passes, y las propiedades únicas de un pase individual en la instancia de objeto Passes.
Por ejemplo, en el siguiente diagrama de un pase simple de Event Ticket, se muestra cómo se combinan los campos que se definen en el EventTicketClass compartido y los campos para un boleto específico definido en EventTicketObject para construir el pase final emitido. Observa cómo se hace referencia al ID de la clase Passes en la propiedad classId del objeto Passes.
Los cambios realizados en una instancia de la clase Passes se propagarán de inmediato en todas las instancias de objetos Passes que hagan referencia a ella. Los cambios que hagas en una instancia de Passes Class se reflejarán en el pase de la app de la Billetera de Google la próxima vez que se sincronicen.
Agrega un pase a la Billetera de Google de un usuario
Para agregar un pase a la Billetera de Google de un usuario, debes crear un token web JSON (JWT) que contenga las reclamaciones que tú (la entidad emisora) estás haciendo sobre la instancia de Objeto de Passes que se guardará en la Billetera de Google del usuario; lo más importante, el ID de objeto de la instancia de Objeto de Passes que le envías al usuario. Luego, el JWT se envía al usuario a través del botón Agregar a la Billetera de Google o el vínculo Agregar a la Billetera de Google.
Después de que un usuario hace clic en el botón o el vínculo para agregar un pase emitido a su Billetera de Google, se vincula a la Cuenta de Google de ese usuario un vínculo la instancia del objeto de los pases codificada en el JWT. Esto significa que, cuando el usuario vuelva a hacer clic en el botón, ya existe un vínculo a ese objeto Passes, por lo que las copias duplicadas no se agregarán a la billetera del usuario.
Si un usuario quita un pase de la app de la Billetera de Google, la instancia del objeto de pases correspondiente se desvincula automáticamente del usuario, pero no se borra. Esto significa que un usuario puede volver a hacer clic en el botón Agregar a la Billetera de Google o en el vínculo para guardar el pase sin necesidad de que se cree una nueva instancia de objeto Passes o JWT.