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 de pases y un objeto de pase. Cada vez que emitas un pase para un usuario, necesitarás una instancia de una clase de pases y un objeto de pase, que le indicarán a la API de Google Wallet qué tipo de pase debe crear, así como los detalles que se mostrarán en el pase, como el valor de una tarjeta de regalo o el nombre del titular de la entrada.
La API de Google Wallet proporciona un conjunto predefinido de clases de pases y objetos de pases de los que creas instancias y, luego, usas para crear un pase que se emite para un usuario, como GiftCardClass y GiftCardObject, GenericClass y GenericObject, y otros.
Cada instancia de clase de pase y objeto de pase se define como un objeto JSON, que tiene un conjunto de propiedades obligatorias y opcionales que corresponden al caso de uso específico previsto para ese tipo de pase.
Clases de pases
Piensa en una clase de pase como una plantilla compartida que se usa para crear uno o más pases que emitirás para tus usuarios. Una clase de pases define un conjunto común de propiedades que se incluirán en todos los pases que la referencien.
Por ejemplo, la siguiente instancia de EventTicketClass define los campos que son comunes a todas las entradas emitidas para un próximo evento(lugar, nombre del evento, emisor, 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 de pases 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 de pase.
Objetos de pases
Mientras que una instancia de una clase de pases especifica un conjunto de propiedades compartidas que se usarán en uno o más pases, un objeto de pases especifica los detalles únicos de un pase específico que se emite para un usuario específico.
Por ejemplo, cuando se crea un pase de entrada para eventos con la API de Google Wallet, 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 de pase 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 para un usuario.
Cómo funcionan las clases de pases con los objetos de pases
Los objetos de pase deben extender una instancia de una clase de pase haciendo referencia a su ID de clase o incluyendo la definición completa de la clase de pase. Esta relación entre una instancia de la clase de pases y una instancia del objeto de pase significa que puedes establecer y actualizar propiedades que son comunes a todos los pases emitidos a través de la instancia de la clase de pases, y propiedades exclusivas de un pase individual en la instancia del objeto de pase.
Por ejemplo, el siguiente diagrama de un pase de entrada a un evento simple muestra cómo los campos definidos en el EventTicketClass compartido y los campos de una entrada específica definidos en el EventTicketObject se combinan para construir el pase final emitido. Observa cómo se hace referencia al ID de la clase de pases en la propiedad classId del objeto de pases.
Los cambios realizados en una instancia de la clase de pase se propagarán de inmediato a todas las instancias del objeto de pase que hagan referencia a ella. La próxima vez que los usuarios sincronicen sus dispositivos, verán los cambios que realices en una instancia de la clase de pase reflejados en el pase de la app de la Billetera de Google.
Cómo agregar 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 declaraciones que tú (el emisor) realizas sobre la instancia del objeto de pase que se guardará en la Billetera de Google del usuario, en particular, el ID del objeto de la instancia del objeto de pase que le emites al usuario. Luego, el JWT se entrega al usuario a través de un botón Agregar a la Billetera de Google o un 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 a la instancia del objeto de pases codificada en el JWT. Esto significa que, cuando el usuario vuelva a hacer clic en el botón, ya existirá un vínculo a ese objeto de pase, por lo que no se agregarán copias duplicadas a la billetera del usuario.
Si un usuario quita un pase de la app de la Billetera de Google, la instancia del objeto Passes 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 o el vínculo Agregar a la Billetera de Google para guardar el pase sin necesidad de crear una nueva instancia de objeto de pase o JWT.