Skip to content
Guia da Central de AjudaFase de integração 6
4 min de leituraVerificado 2026-11-16

Métricas de emissão e utilização

Interprete Criados, Ativos em Wallets, Não instalados, Removidos e a contagem multi-dispositivo Apple.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Saúde dos cartões e ações recomendadas (Zoom)

Acompanhe a proporção entre cartões ativos e não instalados em Pass health e atue sobre as recomendações automáticas para dar seguimento aos cartões que aguardam instalação.

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
TAXONOMIA DE INSTÂNCIA DE CARTÃO VS. REGISTO DE DISPOSITIVO
ETAPA 01
1
CAMADA LÓGICA DE INSTÂNCIA DE CARTÃO (1 Registo de Cartão = 1 serialNumber Único) [ Cartão Criado ]+[ Não Reclamado (unclaimedPasses) ] (0 Registos) (totalPasses)
+[ Ativo (activePasses) ] (>= 1 Registo Ativo) +[ Removido (inactivePasses) ] (Todos Reg. Removidos) +[ Terminal (expiredPasses / voidedPasses) ]
ETAPA 02
Ecossistema Apple Wallet (APNs)
iPhone do Titular (Reg #1)
Apple Watch Empar. (Reg #2)
1 Cartão Ativo = 2 Reg. Dispos.
Ecossistema Google Wallet (REST)
PassObject Ligado à Conta Google
Sinc. Callbacks Guardar/Remover
1 Cartão Ativo = 1 Reg. Objeto
2
CAMADA FÍSICA DE REGISTO DE DISPOSITIVO (installedDevices entre uniqueDevices)

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 1 activePasses no resumo de instâncias, enquanto regista 2 installedDevices nos 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étricaEtiqueta no PainelDefinição Técnica e Base de Avaliação
totalPassesTotal de Cartões EmitidosTotal de registos de cartão emitidos e não eliminados no momento do retrato.
activePassesCartões AtivosInstâncias vivas que possuem atualmente pelo menos um registo de dispositivo contactável (exclui expirados e anulados na visão geral padrão).
inactivePassesCartões RemovidosInstâncias anteriormente guardadas numa Wallet que deixaram de ter registos contactáveis (removedPasses nos relatórios de instalação).
unclaimedPassesCartões Por ReclamarInstâncias emitidas via API, CSV ou PassFlow que nunca foram guardadas numa Wallet (noRegistrationPasses).
expiredPassesCartões ExpiradosInstâncias cuja expirationDate terminou ou cujo estado está marcado como EXPIRED.
voidedPassesCartões AnuladosInstâ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étricaEtiqueta no PainelDefinição Técnica e Base de Avaliação
installedDevicesRegistos de Dispositivo AtivosTotal de registos guardados contactáveis em todos os dispositivos físicos (1 cartão em 2 dispositivos = 2).
inactiveDeviceRegistrationsRegistos de Dispositivo RemovidosRegistos removidos pelo dispositivo ou invalidados após falha permanente de envio push APNs.
totalDeviceRegistrationsTotal de Registos de DispositivoRegistos acumulados em estados ativos e removidos.
uniqueDevicesDispositivos ÚnicosIdentificadores de hardware físicos distintos que mantêm atualmente pelo menos um registo de cartão ativo.
devicePlatformDistributionDistribuição por PlataformaRepartiçã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 chama DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber ou o Google Wallet envia callback de remoção, mais remoções inferidas quando APNs devolve 410 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

EndpointVerbo HTTPDescrição
/api/v1/analytics/passes/overviewGETRetrato de totalPasses, activePasses, inactivePasses, unclaimedPasses, expiredPasses e voidedPasses.
/api/v1/analytics/passes/createdGETSérie temporal de cartões recém-criados agrupada por day, week ou month.
/api/v1/analytics/registrationsGETSérie temporal de registos de dispositivo ativos e desativados na janela selecionada.
/api/v1/analytics/wallet-installationsGETMatriz abrangente que separa estados de instalação ao nível do cartão de eventos de dispositivo.

Exemplo: Matriz Detalhada de Instalações Wallet

HTTP
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>
JSON
{
  "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

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.