4 - Descobrir Antena NFC

Recomendação: Onboarding no primeiro uso

⭐
Implemente um fluxo de onboarding no seu aplicativo para que o usuário localize a antena NFC do dispositivo antes de realizar o primeiro pagamento. Isso reduz significativamente os riscos de timeout na leitura do cartão e erros de aproximação, melhorando a experiência do usuário desde o primeiro uso.

Utilize a classe CardProximityReader do SDK para verificar a posição da antena NFC do dispositivo e monitorar a proximidade do cartão em tempo real.

Permissões

Adicione as seguintes permissões ao AndroidManifest.xml antes de utilizar o CardProximityReader:

<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.VIBRATE" />

Permissão	Finalidade
`NFC`	Leitura de cartão por aproximação
`VIBRATE`	Feedback tátil ao detectar o cartão

Inicialização

Implemente o CardProximityReader em uma Activity ou Fragment que utilizará a proximidade NFC. O ciclo de vida deve gerenciar o enableForegroundDispatch e disableForegroundDispatch:

class CardProximityActivity : Activity() {

    private lateinit var cardProximityReader: CardProximityReader

    override fun onCreate(savedInstanceState: Bundle?) {
        cardProximityReader = CardProximityReader(this)
    }

    override fun onResume() {
        super.onResume()
        cardProximityReader.enableForegroundDispatch(this)  // Ativa a escuta NFC
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        cardProximityReader.handleIntent(intent)  // Processa o evento NFC
    }

    override fun onPause() {
        super.onPause()
        cardProximityReader.disableForegroundDispatch(this)  // Desativa a escuta NFC
    }
}

Listeners disponíveis

O SDK oferece dois callbacks para monitorar a proximidade NFC:

📡onProximityChange

Retorna a proximidade atual do cartão em relação ao dispositivo como um valor do enum NfcProximity.

📶onSignalStrength

Retorna a força do sinal NFC como um valor inteiro — quanto maior, mais próximo o cartão.

onProximityChange

Retorna um valor do enum NfcProximity indicando a distância do cartão:

Valor	Significado
`VERY_CLOSE`	Muito perto da antena
`CLOSE`	Perto da antena
`FAR`	Longe da antena
`UNKNOWN`	Não foi possível determinar

enum class NfcProximity {
    VERY_CLOSE,  // Muito perto
    CLOSE,       // Perto
    FAR,         // Longe
    UNKNOWN      // Desconhecido
}

cardProximityReader.setNfcSignalListener(object : NfcSignalListener {
    override fun onProximityChange(proximity: NfcProximity) {
        Log.d("NFC_PROXIMITY", "$proximity")
    }
})

onSignalStrength

Retorna a força do sinal NFC como um Int:

cardProximityReader.setNfcSignalListener(object : NfcSignalListener {
    override fun onSignalStrength(signalStrength: Int) {
        Log.d("NFC_PROXIMITY", "$signalStrength")
    }
})

Exemplo completo

Implementação completa com ambos os listeners em uma Activity:

class CardProximityActivity : Activity() {

    private lateinit var cardProximityReader: CardProximityReader
    private val log = "NFC_PROXIMITY"

    override fun onCreate(savedInstanceState: Bundle?) {
        cardProximityReader = CardProximityReader(this)

        // Configura ambos os listeners
        cardProximityReader.setNfcSignalListener(object : NfcSignalListener {
            override fun onProximityChange(proximity: NfcProximity) {
                Log.d(log, "$proximity")  // VERY_CLOSE, CLOSE, FAR, UNKNOWN
            }

            override fun onSignalStrength(signalStrength: Int) {
                Log.d(log, "$signalStrength")  // Valor inteiro da força do sinal
            }
        })
    }

    override fun onResume() {
        super.onResume()
        cardProximityReader.enableForegroundDispatch(this)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        cardProximityReader.handleIntent(intent)
    }

    override fun onPause() {
        super.onPause()
        cardProximityReader.disableForegroundDispatch(this)
    }
}

💡
Ao aproximar o cartão, o dispositivo irá vibrar e emitir um som, indicando a localização aproximada da antena NFC. Utilize esse feedback para orientar o usuário a posicionar o cartão corretamente.