Apple Wallet: relevantDates, locations y geofencing — cuándo un pase aparece solo en la pantalla de bloqueo

Un pase de Apple Wallet puede ser relevante por fecha, por lugar o por ambos, y cuando lo es, el sistema lo ofrece en la pantalla de bloqueo sin que nadie envíe nada: ni push, ni cuota. La fecha va en relevantDates (el singular relevantDate está obsoleto), el lugar en locations —hasta 10, con radio opcional maxDistance— o en beacons, y el texto que acompaña la sugerencia (relevantText) solo existe pegado a un lugar o a un beacon, nunca a una fecha. En Google el equivalente hoy es merchantLocations, con radio fijado por Google y sin texto.

La relevancia es el canal más barato del wallet y el más mal entendido, en parte porque la documentación vigente y la archivada no cuentan lo mismo. Esto es lo que dice la referencia viva a agosto de 2026, cómo lo usamos por tipo de pase, y la cicatriz que nos costó entenderlo.

Relevancia por fecha: relevantDates

La referencia del objeto Pass define relevantDate como «la fecha y hora en que el pase se vuelve relevante, como la hora de inicio de una película» — y lo marca obsoleto: «usa relevantDates en su lugar». relevantDates es «un arreglo de objetos que representan intervalos de fecha que el sistema usa para mostrar un pase relevante». Cada entrada admite dos formas:

• date — un instante; «Wallet calcula automáticamente un intervalo de relevancia a partir de esta fecha».
• startDate + endDate — un intervalo explícito; endDate es «obligatorio cuando se provee startDate».

Los valores son fechas completas con horas y minutos, opcionalmente segundos. En la práctica emitimos ambas claves mientras convivan versiones de iOS —el singular para los sistemas viejos, el arreglo para los nuevos— y elegimos la forma según el pase: para una entrada, un intervalo corto alrededor de la función; para una factura, un instante tres días antes del vencimiento; para un carné o una cuota, el propio vencimiento; para una membresía, el fin de su vigencia. Un matiz de nombres: el instante dentro del arreglo lo emitimos con el alias relevantDate —el nombre con el que la clave nació y que la herramienta de firma sigue aceptando—; date es el nombre que la referencia viva documenta, y conviene emitirlo también. Relevancia no es expiración: una dice cuándo ofrecer el pase, la otra cuándo dejarlo de valer.

Un detalle que despista: el artículo de Apple sobre la pantalla de bloqueo, a agosto de 2026, todavía usa relevantDate en singular en su ejemplo. La referencia manda.

Relevancia por lugar: locations, maxDistance, beacons

locations es «un arreglo de hasta 10 objetos que representan ubicaciones geográficas que el sistema usa para mostrar un pase relevante». Cada ubicación lleva latitude y longitude obligatorias, altitude opcional, y relevantText opcional: «el texto a mostrar en la pantalla de bloqueo cuando el pase es relevante — por ejemplo, la descripción de un lugar cercano, como “Store nearby on 1st and Main”». El radio se acota con maxDistance, en metros: «el sistema usa la menor entre esta distancia y la distancia por defecto» — el valor por defecto no se publica.

beacons es la variante de interior: hasta diez UUIDs de iBeacon (proximityUUID obligatorio, major y minor opcionales), con su propio relevantText; para más de diez beacons, Apple indica agrupar por UUID y distinguir cada uno por major y minor.

Cómo lo usamos. Una tarjeta de lealtad lleva las sedes geolocalizadas activas de la operación —varias sedes, un solo panel— con un texto del estilo Tu tarjeta de {programa}, para que se sugiera al llegar a la sede. Una entrada de evento lleva las coordenadas del recinto con Tu entrada para {evento}, además de su intervalo de fecha. Las diez ubicaciones son un tope real: si la operación tiene más sedes, van diez — hoy las diez primeras por nombre; elegir las mejores, como recomienda Apple, es un criterio que todavía no aplicamos.

Cómo combinan fecha y lugar (y la regla por estilo)

La regla: fecha y lugar cuando declaras ambos; solo fecha o solo lugar cuando falta el otro; cupones, store cards y genéricos exigen ubicación si llevan cualquier otra relevancia. El artículo de Apple sobre la pantalla de bloqueo lo fija en prosa, y conviene citarlo porque la tabla clásica por estilo ya no existe en la documentación viva:

• «Un pase puede ser relevante en una fecha, en una ubicación, o ambas.» La fecha sola vale para boarding passes, entradas de evento y pases genéricos.
• «Cupones, store cards y pases genéricos deben proveer ubicaciones si agregaste cualquier otro tipo de información de relevancia al pase.» Una tarjeta de lealtad con solo una fecha no se ofrece: necesita sus sedes. Y sí: el pase genérico aparece en las dos frases — Apple es ambiguo ahí, y la única prueba válida es el dispositivo.
• «El sistema muestra el pase en la pantalla de bloqueo si coinciden la fecha y alguna ubicación. Los pases sin ubicaciones se muestran en la fecha relevante. Igualmente, los pases sin fecha relevante se muestran cuando coincide una de las ubicaciones.»
• «Prueba la configuración de relevancia en un dispositivo. El simulador no muestra pases en la pantalla de bloqueo.» Lo único que vale como evidencia es el teléfono real.

La consecuencia de diseño: para una entrada con fecha y recinto, el pase aparece solo cuando el titular está en el lugar a la hora — no en su casa la mañana del evento. Si quieres el recordatorio a domicilio, eso es un aviso, no relevancia; y los avisos tienen su propio canal y sus límites.

La cicatriz: relevantText no existe a nivel raíz

relevantText no es una clave del objeto Pass: solo existe dentro de locations y beacons. Nos costó semanas entenderlo. Emitíamos, en los pases con fecha de pago, un relevantText a nivel raíz del pass.json — Vence el {fecha} — y lo vimos desaparecer al firmar. Lo registramos como limitación de la herramienta de firma (passkit-generator, la librería que usamos): su validador elimina las claves que no conoce, y esa clave no sobrevivía. Hasta que leímos la referencia con calma: relevantText no es una clave del objeto Pass; solo existe dentro de cada entrada de locations y de beacons. La herramienta hacía bien en tirarla, y aunque un parche la hubiera dejado pasar, ningún dispositivo la habría dibujado.

La corrección fue conceptual antes que técnica: la relevancia por fecha se entrega con relevantDates y sin texto propio — el sistema ofrece el pase, y el pase habla por sí mismo —; el texto existe únicamente donde Apple lo puso, pegado a un lugar. Y la lección que vale para cualquier campo de pass.json: cuando algo «desaparece» al firmar, la primera pregunta no es qué hace la librería, sino si la clave existe en el modelo.

Qué pasa al actualizar la relevancia

Las claves de relevancia son parte del pass.json, así que cambiarlas es emitir una nueva versión del pase: el dispositivo la descarga tras el push silencioso y la relevancia nueva aplica desde ahí. Apple lo dice de las ubicaciones —«actualiza el pase para cambiar el arreglo de ubicaciones relevantes»— y vale igual para las fechas: una función reprogramada que no se re-empuja sigue apareciendo en la pantalla de bloqueo a la hora vieja.

Google a agosto de 2026: merchantLocations, no locations

En la referencia de Google Wallet, locations[] figura obsoleto con una nota explícita: «este campo actualmente no está soportado para disparar notificaciones geográficas». El reemplazo es merchantLocations[], disponible en clases y objetos: «hay un máximo de diez por clase [u objeto]; cualquier ubicación adicional será rechazada. Estas ubicaciones disparan una notificación cuando el usuario entra dentro de un radio fijado por Google alrededor del punto». El tipo MerchantLocation lo precisa: «cuando el usuario está dentro de un radio de esta latitud/longitud y permanece ahí, Google dispara una notificación; cuando sale del radio, la notificación se oculta».

Solo latitud y longitud: no hay texto propio ni radio configurable, y la prueba previa al lanzamiento que Google propone es literalmente acercarse a una de las ubicaciones y esperar la alerta de «comercio cercano».

La relevancia por fecha no tiene en Google un equivalente directo de relevantDates; lo que existe es la vigencia del objeto (validTimeInterval), que gobierna cuándo el pase deja de valer, no cuándo se ofrece — el detalle está en expirar un pase. A agosto de 2026 no emitimos merchantLocations; cuando lo hagamos será con la misma regla de diez sedes.

Preguntas frecuentes

¿relevantDate sigue funcionando o hay que usar relevantDates?

La referencia viva de Apple marca relevantDate como obsoleto y remite a relevantDates, un arreglo de intervalos: cada entrada lleva date (un instante, y Wallet calcula la ventana) o startDate más endDate, obligatorio si declaras startDate. En la práctica emitimos ambos mientras convivan versiones de iOS: el singular lo leen los sistemas viejos y el arreglo los nuevos.

¿Puedo mostrar un texto en la pantalla de bloqueo solo por fecha, sin ubicación?

No. El texto de relevancia (relevantText) solo existe pegado a una ubicación o a un beacon; no es una clave del nivel raíz del pase. Por fecha, el sistema ofrece el pase sin texto propio. Lo aprendimos emitiendo un «Vence el…» a nivel raíz que la herramienta de firma eliminaba — y no era un defecto de la herramienta: la clave no existe en el modelo de Apple.

¿Cuántas ubicaciones acepta un pase?

Diez, según la referencia viva de Apple. Si tu operación tiene más sedes, Apple recomienda empezar por las mejores y actualizar el pase cuando cambien — en nuestra plataforma hoy van las diez primeras por nombre, el criterio de «mejores» está pendiente —; el radio lo acotas con maxDistance, y el sistema usa el menor entre tu valor y su distancia por defecto, que Apple no publica en metros.

¿Google Wallet tiene geofencing?

Sí, pero distinto. El campo locations está obsoleto y Google declara que no dispara notificaciones geográficas; el reemplazo es merchantLocations, hasta diez por clase u objeto: cuando el usuario entra y permanece dentro de un radio fijado por Google, Google dispara la notificación y la oculta al salir. No hay texto propio ni radio configurable.