O que um aplicativo iOS precisa para emular um cartão?

As autorizações vêm primeiro

A CardSession, a partir do iOS 17.4, é a classe que emula um cartão, e a documentação da Apple lista o que ela cobre no Espaço Econômico Europeu: pagamentos em loja, chaves de carro, transporte de circuito fechado, crachás corporativos, chaves de hotel, fidelidade e bilhetes de evento.

Três autorizações a governam. com.apple.developer.nfc.hce permite a API em absoluto, e sem ela criar uma sessão levanta um erro fatal. A autorização dos prefixos de identificador lista por que o aplicativo responde: identificadores de aplicação inteiros, identificadores de provedor registrados, ou prefixos pelo menos tão longos quanto o identificador do provedor. A autorização do aplicativo por aproximação padrão deixa uma pessoa escolher o aplicativo nos Ajustes como o padrão por aproximação.

Cada uma das três páginas aponta para o mesmo lugar, um formulário de pedido para transações por aproximação baseadas em emulação de cartão pelo host, para aplicativos bancários e de carteira no Espaço Econômico Europeu. O lado comercial disso está coberto pela página da emulação no iPhone; a consequência técnica é que o código abaixo só roda onde a Apple disse sim.

Duas conferências antes de qualquer coisa aparecer

A Apple pede três valores antes de uma sessão ser criada: NFCReaderSession.readingAvailable, CardSession.isSupported para o aparelho, e CardSession.isEligible para o ambiente atual, que é assíncrono. A referência é explícita sobre por que cada um importa: criar uma sessão num aparelho não suportado levanta um erro fatal, e num ambiente não elegível mostraria uma interface de sessão de cartão do sistema à toa.

Então a conferência fica antes do botão, não depois dele. Um aplicativo que se oferece para apresentar um cartão e depois falha no teste de elegibilidade já prometeu algo que o sistema não vai entregar.

A sessão, evento por evento

Uma sessão de cartão é um fluxo em vez de um delegado. O aplicativo a cria, percorre eventStream, e recebe sessionStarted assim que o aplicativo detém o recurso NFC, depois readerDetected quando o aparelho percebe o campo de um leitor.

A emulação começa quando o aplicativo chama startEmulation(), que apresenta a interface modal do sistema, com alertMessage posta de antemão. Daí em diante cada evento carrega uma carga útil APDU a processar e a responder com respond(response:), e a Apple avisa que um leitor pode tratar uma resposta atrasada como um tempo esgotado. readerDeselected chega quando o leitor vai embora, stopEmulation(status:) fecha a interface de rádio com um estado final mostrado ao usuário, e invalidate() libera a sessão.

startEmulation() lança onde a plataforma recusa: o sistema não está disponível, o acesso não foi aceito, a elegibilidade falhou, ou o rádio está desligado. Esses quatro casos merecem mensagens distintas, já que só um deles é um problema que o usuário consegue resolver.

Que aplicativo um toque alcança

O aplicativo por aproximação padrão responde a um toque a menos que outro aplicativo peça o campo. NFCPresentmentIntentAssertion é esse pedido: adquirida do primeiro plano, ela impede o aplicativo padrão do sistema de ser lançado em resposta a um gesto ou ao campo de um leitor, e a Apple a prende a uma pessoa escolhendo ativamente uma credencial no seu aplicativo.

Ela não dura. A asserção expira quando o objeto é desinicializado, quando o aplicativo vai para segundo plano, ou depois de quinze segundos, e uma nova só pode ser adquirida depois de um intervalo de espera de quinze segundos. Ela também não é exigida antes de apresentar a interface.

O Android arranja a mesma questão de outro jeito, com um papel de carteira e uma preferência de primeiro plano que qualquer aplicativo pode usar; a página do encaminhamento cobre isso. As plataformas concordam num ponto: o usuário, e não o leitor, decide que aplicativo fala.