Descripción General
La interpretación precisa de la telemetría de billetera requiere una distinción arquitectónica estricta entre Instancias de Pases (registros lógicos de credenciales emitidos en la base de datos e identificados por UUID id, serialNumber y un externalId de origen opcional) y Registros de Dispositivos (dispositivos móviles físicos o relojes inteligentes que almacenan activamente esas credenciales asociadas al bundleId / passTypeIdentifier de Apple de la plantilla o al ID de objeto de Google Wallet).
Passinstance aplica esta separación en metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS y WALLET_INSTALLATION_METRIC_DEFINITIONS), mostrada visualmente en el Panel en Analíticas -> Pases (/analytics/passes) y a través de /api/v1/analytics/*, para que los equipos de marketing y los administradores de facturación nunca confundan los enlaces generados con las tarjetas de billetera instaladas.
Separación Arquitectónica: Instancias de Pases frente a Registros de Dispositivos
Importante: En
GET /api/v1/analytics/wallet-installations, un único pase instalado tanto en el iPhone como en el Apple Watch de un cliente cuenta como 1activePassesen el resumen de Instancias de Pases, mientras que registra 2installedDevicesen el resumen de Registros de Dispositivos porque APNs entrega notificaciones push a cada token de dispositivo de forma independiente.
Definiciones Canónicas de Métricas (metric-definitions.ts)
Métricas de Instancias de Pases
| Clave de Métrica | Etiqueta en el Panel | Definición Técnica y Base de Evaluación |
|---|---|---|
totalPasses | Total de Pases Emitidos | Total de registros de pases emitidos y no eliminados en el momento de la instantánea. |
activePasses | Pases Activos | Instancias de pases en vivo que cuentan actualmente con al menos un registro de dispositivo alcanzable (excluye pases vencidos y anulados en el resumen estándar de pases). |
inactivePasses | Pases Eliminados | Instancias de pases en vivo guardadas previamente en una billetera que ya no tienen ningún registro de dispositivo alcanzable (removedPasses en los informes de instalación). |
unclaimedPasses | Pases No Reclamados | Instancias de pases en vivo emitidas mediante API, CSV o PassFlow que nunca se han guardado en la billetera de un dispositivo (noRegistrationPasses). |
expiredPasses | Pases Vencidos | Instancias de pases cuya expirationDate ha pasado o cuyo estado está marcado como EXPIRED. |
voidedPasses | Pases Anulados | Instancias de pases revocadas o anuladas en el servidor mediante el panel, un flujo de trabajo o VOIDED_AFTER_SCAN scan mode. |
Métricas de Registros de Dispositivos
| Clave de Métrica | Etiqueta en el Panel | Definición Técnica y Base de Evaluación |
|---|---|---|
installedDevices | Registros de Dispositivos Activos | Total de registros de pases guardados y alcanzables en todos los dispositivos físicos (1 pase en 2 dispositivos = 2). |
inactiveDeviceRegistrations | Registros de Dispositivos Eliminados | Registros de pases guardados que fueron dados de baja por el dispositivo o invalidados por un fallo permanente de envío push en APNs. |
totalDeviceRegistrations | Total de Registros de Dispositivos | Registros acumulados de pases guardados tanto en estado activo como eliminado. |
uniqueDevices | Dispositivos Únicos | Identificadores de hardware de dispositivos físicos distintos que mantienen actualmente al menos un registro de pase activo. |
devicePlatformDistribution | Distribución por Plataforma de Dispositivo | Desglose de registros de dispositivos activos por ecosistema de billetera (APPLE_WALLET frente a GOOGLE_WALLET) y familia de sistema operativo. |
Matices de la Telemetría de Billetera y Casos Especiales
Además de los estados confirmados, el informe GET /api/v1/analytics/wallet-installations realiza un seguimiento de las transiciones a nivel de evento y de los estados límite:
-
installEvents(Instalaciones en Billetera): Registros de dispositivos creados durante el período del informe, contados una vez por cada par único de pase y dispositivo. Reinstalar un pase ya registrado en el mismo dispositivo no infla el recuento de instalaciones. -
removalEvents(Eliminaciones de Billetera): Registrados cuando Apple Wallet llama aDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumbero Google Wallet envía un callback de eliminación, además de las eliminaciones inferidas cuando APNs devuelve410 Unregistered. -
otherStatePasses(Registros No Resueltos): Pases cuyos únicos registros están pendientes, suspendidos o en un estado indeterminado que no demuestra ni una instalación activa ni una eliminación confirmada. -
noRegistrationPasses(Sin Instalación Confirmada): Pases con cero registros de dispositivo. En Apple Wallet, la instalación siempre activa una llamada inmediata de registro de dispositivo; en Google Wallet, la instalación depende de los callbacks de guardado.
Endpoints Principales de la API de Emisión y Registro
| Endpoint | Verbo HTTP | Descripción |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Instantánea de totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses y voidedPasses. |
/api/v1/analytics/passes/created | GET | Serie temporal de instancias de pases recién creadas agrupadas por day, week o month. |
/api/v1/analytics/registrations | GET | Serie temporal de registros de dispositivos activos y desactivados durante la ventana seleccionada. |
/api/v1/analytics/wallet-installations | GET | Matriz integral que separa los estados de instalación a nivel de pase de los eventos de registro a nivel de dispositivo. |
Ejemplo: Matriz Detallada de Instalación en Billetera
GET /api/v1/analytics/wallet-installations?range=last_30days&templateId=b4f29c10-83e1-4a7b-9d12-56e8012a9c04 HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"snapshotAt": "2026-11-15T23:59:59.999Z",
"passes": {
"totalPasses": 5000,
"activePasses": 3850,
"removedPasses": 310,
"otherStatePasses": 15,
"noRegistrationPasses": 825
},
"registrations": {
"installedDevices": 4290,
"inactiveDeviceRegistrations": 365,
"totalDeviceRegistrations": 4655,
"uniqueDevices": 4180,
"devicePlatformDistribution": {
"apple": 2910,
"google": 1380
}
},
"periodEvents": {
"passesCreated": 640,
"installEvents": 595,
"removalEvents": 42
}
}
Documentación Relacionada
-
Comprenda cómo se aplican los recuentos de pases activos a los niveles de suscripción en Pases Activos y Límites de Uso.
-
Explore los controles de gráficos del espacio de trabajo en Panel de Analíticas.
