Tag NFC

Legga e scriva tag NFC, come carte fedeltà, badge di accesso, adesivi e smart card, direttamente dalla Sua app Android. L'SDK comunica con il lettore del dispositivo stesso: l'NFC di Android su un telefono, oppure il lettore contactless di un terminale Sunmi della serie P. Non c'è alcun plugin di mezzo.

Le sessioni con i tag sono distribuite in artefatti facoltativi, com.tapaya:accept-nfc e, per i terminali Sunmi, com.tapaya:accept-nfc-sunmi. Li aggiunga solo se Le servono; i pagamenti con carta funzionano allo stesso modo con o senza di essi.

Dispositivi supportati

I terminali Sunmi della serie P non dispongono dell'NFC di Android; la loro antenna si trova dietro il modulo di pagamento. accept-nfc-sunmi la raggiunge tramite il servizio di pagamento di Sunmi e subentra all'NFC di Android ogni volta che tale servizio è installato.

Su un dispositivo senza un lettore utilizzabile, isSupported() restituisce false e openSession() genera l'errore NOT_SUPPORTED.

Tag supportati

Come funziona

1. La Sua app chiama Accept.nfc.openSession(activity).
2. L'SDK attiva il lettore del dispositivo e attende un avvicinamento.
3. Il cliente avvicina un tag e openSession() restituisce una TagSession con l'UID e la famiglia del tag.
4. La Sua app legge e scrive tramite la sessione, un comando alla volta.
5. La Sua app chiama close(), che libera il lettore per i pagamenti e per altre sessioni con i tag.

Prerequisiti

• Un dispositivo supportato.
• L'Accept SDK installato e inizializzato. Chiamare isSupported() o openSession() prima di Accept.initialize lancia NotInitialized.

Le sessioni con i tag non richiedono che un esercente abbia effettuato l'accesso, né il plugin Tapaya Terminal, né l'autorizzazione alla posizione. Gli artefatti aggiungono al manifest ciò di cui hanno bisogno:

• accept-nfc aggiunge l'autorizzazione NFC e contrassegna android.hardware.nfc come non obbligatorio, così Play mantiene la Sua app disponibile sui terminali Sunmi, che non dispongono dell'NFC di Android.
• accept-nfc-sunmi aggiunge l'autorizzazione com.sunmi.perm.CONTACTLESS_CARD e una voce <queries> per il servizio di pagamento di Sunmi. Incorpora Sunmi PayLib.

Integrazione

dependencies {
    implementation("com.tapaya:accept-nfc:1.20.0")

    // Only if you run on Sunmi P-series terminals
    implementation("com.tapaya:accept-nfc-sunmi:1.20.0")
}

import com.tapaya.accept.nfc.nfc

if (Accept.nfc.isSupported()) {
    showScanTagButton()
}

val session = try {
    Accept.nfc.openSession(activity)
} catch (e: TagSessionException) {
    when (e.reason) {
        TagErrorReason.TIMEOUT -> showMessage("No tag detected. Try again.")
        TagErrorReason.READER_BUSY -> showMessage("The reader is busy. Try again soon.")
        TagErrorReason.NFC_DISABLED -> promptToEnableNfc()
        else -> showMessage("Can't read tags on this device.")
    }
    return
}

try {
    showTag(session.info.uidHex, session.info.family)
    // read and write...
} finally {
    session.close()
}

when (session.info.family) {
    TagFamily.NTAG, TagFamily.ULTRALIGHT, TagFamily.ULTRALIGHT_EV1,
    TagFamily.ULTRALIGHT_C, TagFamily.TYPE2_OTHER -> readType2Tag(session)
    TagFamily.MIFARE_CLASSIC_MINI, TagFamily.MIFARE_CLASSIC_1K,
    TagFamily.MIFARE_CLASSIC_4K -> readClassicCard(session)
    TagFamily.ISO_DEP -> readSmartCard(session)
    else -> showMessage("This tag isn't supported.")
}

// Protected NTAG and Ultralight EV1 tags only
session.passwordAuth(password = byteArrayOf(0x12, 0x34, 0x56, 0x78))

val pages = session.readPages(startPage = 4)  // pages 4 to 7
session.writePage(page = 4, data = byteArrayOf(0x01, 0x02, 0x03, 0x04))

// Raw GET_VERSION command
val version = session.transceiveType2(byteArrayOf(0x60))

session.authenticateClassic(block = 4, keyType = MifareKeyType.A, key = sectorKey)
val block = session.readBlock(4)
session.writeBlock(4, newContent)

// Value blocks: change the value, then write it back
session.decrement(block = 5, value = 1)
session.transfer(block = 5)

val key = candidateKeys.firstOrNull { key ->
    try {
        session.authenticateClassic(block = 4, keyType = MifareKeyType.A, key = key)
        true
    } catch (e: TagSessionException) {
        if (e.reason != TagErrorReason.AUTH_FAILED) throw e
        false
    }
} ?: error("no key for sector 1")

val select = byteArrayOf(0x00, 0xA4.toByte(), 0x04, 0x00, 0x07,
    0xA0.toByte(), 0x00, 0x00, 0x00, 0x03, 0x10, 0x10, 0x00)
val response = session.transmitApdu(select)
val sw = response.takeLast(2)   // [0x90, 0x00] on success

session.ended.filterNotNull().first().let { reason ->
    when (reason) {
        TagSessionEndReason.CARD_REMOVED -> showMessage("Card removed")
        TagSessionEndReason.PAYMENT -> showMessage("A payment took over the reader")
        TagSessionEndReason.ACTIVITY_PAUSED -> showMessage("Keep the app in the foreground")
        else -> Unit
    }
}

Gestione degli errori

Gli errori relativi ai tag lanciano TagSessionException, il cui reason indica cosa fare dopo. Chiamare l'API prima che l'SDK sia configurato lancia NotInitialized. TagSessionException non è un'AcceptException, quindi intercetti le due separatamente:

try {
    val session = Accept.nfc.openSession(activity)
    // ...
} catch (e: TagSessionException) {
    // reason-specific handling, see the tables below
} catch (e: NotInitialized) {
    // Accept.initialize hasn't been called
}

Un argomento chiave, blocco o pagina di lunghezza o segno errati, oppure un frame o un'APDU vuoti, lancia IllegalArgumentException prima che qualcosa raggiunga il tag.

Apertura di una sessione

Invio di un comando

Sessione terminata

Timeout

Per modificare i valori predefiniti, passi TagTimeouts a openSession():

Accept.nfc.openSession(activity, TagTimeouts(tapWait = 15.seconds, idle = 30.seconds))

Ogni valore deve essere maggiore di zero. Creare TagTimeouts con un valore al di fuori di questi intervalli lancia IllegalArgumentException.

Da sapere

• Un solo lettore. Il dispositivo ha un solo lettore contactless, quindi è possibile una sola sessione con il tag o una sola attesa di avvicinamento alla volta. Un secondo openSession() genera l'errore READER_BUSY. I pagamenti avviati con Accept.payments.pay() chiudono prima la sessione; i pagamenti avviati al di fuori dell'SDK non possono essere coordinati, quindi mantenga le sessioni brevi.
• Annullare un comando non lo annulla sul tag. Nel momento in cui annulla la coroutine, il comando ha già raggiunto il tag e viene comunque eseguito; viene scartato solo il suo risultato. Un writeBlock annullato può comunque modificare il tag.
• I comandi vengono eseguiti in ordine. I metodi della sessione possono essere chiamati da qualsiasi coroutine; raggiungono il tag uno alla volta, nell'ordine in cui li chiama.
• I dati dei tag restano fuori dai log. L'SDK non registra mai nei log chiavi, password o dati dei tag e maschera gli UID (ad es. 04A1…E5F6). Il modo in cui la Sua app salva e mostra i dati dei tag dipende da Lei.

Testare l'integrazione

Su un telefono e, se supporta i terminali Sunmi della serie P, anche su uno di questi:

1. Verifichi che isSupported() restituisca true su entrambi e false su un dispositivo senza NFC.
2. Avvicini un tag NTAG o Ultralight e verifichi che la sessione riporti l'UID corretto e che readPages(0) restituisca 16 byte. Poi esegua writePage e rilegga la pagina.
3. Su MIFARE Classic, esegua l'autenticazione con una chiave errata e verifichi AUTH_FAILED, poi con quella corretta.
4. Annulli openSession() durante l'attesa dell'avvicinamento e apra subito una nuova sessione.
5. Avvii un pagamento durante una sessione: la sessione dovrebbe chiudersi come PAYMENT e il pagamento andare a buon fine. Allontani il tag durante un'altra sessione: la sessione dovrebbe chiudersi come CARD_REMOVED.
6. Su un telefono, disattivi l'NFC e verifichi NFC_DISABLED. Durante una sessione, porti l'app in background e verifichi che la sessione si chiuda come ACTIVITY_PAUSED.