Visão geral
Uma leitura rigorosa da telemetria Wallet exige uma distinção arquitetural clara entre Instâncias de Cartão (registos lógicos na base de dados indexados pelo UUID id, serialNumber e pelo eventual externalId de origem) e Registos de Dispositivo (dispositivos móveis ou wearables físicos que guardam ativamente essas credenciais associados ao bundleId / passTypeIdentifier Apple ou Object ID do Google Wallet do modelo).
O Passinstance impõe esta separação em metric-definitions.ts (PASS_ANALYTICS_METRIC_DEFINITIONS e WALLET_INSTALLATION_METRIC_DEFINITIONS), visível no Painel em Analítica -> Cartões (/analytics/passes) e via /api/v1/analytics/*, garantindo que equipas de marketing e faturação nunca confundem ligações criadas com cartões efetivamente instalados na Wallet.
Separação Arquitetural: Instâncias de Cartão vs. Registos de Dispositivo
Importante: Em
GET /api/v1/analytics/wallet-installations, um único cartão instalado simultaneamente no iPhone e no Apple Watch de um cliente conta como 1activePassesno resumo de instâncias, enquanto regista 2installedDevicesnos registos de dispositivo porque o APNs envia notificações push de forma independente para cada token.
Definições Canónicas de Métricas (metric-definitions.ts)
Métricas de Instância de Cartão
| Chave da Métrica | Etiqueta no Painel | Definição Técnica e Base de Avaliação |
|---|---|---|
totalPasses | Total de Cartões Emitidos | Total de registos de cartão emitidos e não eliminados no momento do retrato. |
activePasses | Cartões Ativos | Instâncias vivas que possuem atualmente pelo menos um registo de dispositivo contactável (exclui expirados e anulados na visão geral padrão). |
inactivePasses | Cartões Removidos | Instâncias anteriormente guardadas numa Wallet que deixaram de ter registos contactáveis (removedPasses nos relatórios de instalação). |
unclaimedPasses | Cartões Por Reclamar | Instâncias emitidas via API, CSV ou PassFlow que nunca foram guardadas numa Wallet (noRegistrationPasses). |
expiredPasses | Cartões Expirados | Instâncias cuja expirationDate terminou ou cujo estado está marcado como EXPIRED. |
voidedPasses | Cartões Anulados | Instâncias revogadas ou anuladas do lado do servidor via painel, fluxo de trabalho ou VOIDED_AFTER_SCAN scan mode. |
Métricas de Registo de Dispositivo
| Chave da Métrica | Etiqueta no Painel | Definição Técnica e Base de Avaliação |
|---|---|---|
installedDevices | Registos de Dispositivo Ativos | Total de registos guardados contactáveis em todos os dispositivos físicos (1 cartão em 2 dispositivos = 2). |
inactiveDeviceRegistrations | Registos de Dispositivo Removidos | Registos removidos pelo dispositivo ou invalidados após falha permanente de envio push APNs. |
totalDeviceRegistrations | Total de Registos de Dispositivo | Registos acumulados em estados ativos e removidos. |
uniqueDevices | Dispositivos Únicos | Identificadores de hardware físicos distintos que mantêm atualmente pelo menos um registo de cartão ativo. |
devicePlatformDistribution | Distribuição por Plataforma | Repartição dos registos ativos por ecossistema Wallet (APPLE_WALLET vs. GOOGLE_WALLET) e família de SO. |
Nuances e Casos Limite na Telemetria Wallet
Além dos estados confirmados, GET /api/v1/analytics/wallet-installations acompanha transições por evento:
-
installEvents(Instalações na Wallet): Registos de dispositivo criados no período consultado, contados uma única vez por par cartão-dispositivo. Reinstalar um cartão já registado no mesmo aparelho não inflaciona a contagem. -
removalEvents(Remoções da Wallet): Registados quando o Apple Wallet chamaDELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumberou o Google Wallet envia callback de remoção, mais remoções inferidas quando APNs devolve410 Unregistered. -
otherStatePasses(Registos Indeterminados): Cartões cujos únicos registos estão pendentes, suspensos ou num estado intermédio que não comprova instalação ativa nem remoção confirmada. -
noRegistrationPasses(Sem Instalação Confirmada): Cartões com zero registos associados. No Apple Wallet a instalação aciona sempre um registo imediato; no Google Wallet depende de callbacks de gravação.
Endpoints Principais de Emissão e Registo na API
| Endpoint | Verbo HTTP | Descrição |
|---|---|---|
/api/v1/analytics/passes/overview | GET | Retrato de totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses e voidedPasses. |
/api/v1/analytics/passes/created | GET | Série temporal de cartões recém-criados agrupada por day, week ou month. |
/api/v1/analytics/registrations | GET | Série temporal de registos de dispositivo ativos e desativados na janela selecionada. |
/api/v1/analytics/wallet-installations | GET | Matriz abrangente que separa estados de instalação ao nível do cartão de eventos de dispositivo. |
Exemplo: Matriz Detalhada de Instalações Wallet
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
}
}
Documentação Relacionada
-
Perceba como as contagens ativas se aplicam aos escalões em Cartões Ativos e Limites de Utilização.
-
Explore controlos gráficos do espaço no Painel Analítico.
