NFC tagy

Čítajte a zapisujte NFC tagy, napríklad vernostné karty, prístupové karty, nálepky a čipové karty, priamo zo svojej aplikácie pre Android. SDK komunikuje s vlastnou čítačkou zariadenia: na telefóne je to Android NFC, na termináli Sunmi radu P jeho bezkontaktná čítačka. Nie je medzi nimi žiadny plugin.

Relácie s tagmi sú súčasťou voliteľných artefaktov com.tapaya:accept-nfc a pre terminály Sunmi com.tapaya:accept-nfc-sunmi. Pridajte ich len vtedy, keď ich potrebujete; platby kartou fungujú s nimi aj bez nich rovnako.

Podporované zariadenia

Terminály Sunmi radu P nemajú Android NFC; ich anténa sa nachádza za platobným modulom. accept-nfc-sunmi k nej pristupuje cez platobnú službu Sunmi a vždy, keď je táto služba nainštalovaná, nahrádza Android NFC.

Na zariadení bez použiteľnej čítačky vracia isSupported() hodnotu false a openSession() zlyhá s NOT_SUPPORTED.

Podporované tagy

Ako to funguje

1. Vaša aplikácia zavolá Accept.nfc.openSession(activity).
2. SDK zapne čítačku zariadenia a čaká na priloženie.
3. Zákazník priloží tag a openSession() vráti TagSession s UID a rodinou tagu.
4. Vaša aplikácia číta a zapisuje prostredníctvom relácie, vždy po jednom príkaze.
5. Vaša aplikácia zavolá close(), čím uvoľní čítačku pre platby a ďalšie relácie s tagmi.

Predpoklady

• Podporované zariadenie.
• Accept SDK nainštalované a inicializované. Volanie isSupported() alebo openSession() pred Accept.initialize vyhodí NotInitialized.

Relácie s tagmi nevyžadujú prihláseného obchodníka, plugin Tapaya Terminal ani oprávnenie na polohu. Artefakty si do vášho manifestu pridajú, čo potrebujú:

• accept-nfc pridá oprávnenie NFC a označí android.hardware.nfc ako nepovinné, takže Play ponechá vašu aplikáciu dostupnú aj na termináloch Sunmi, ktoré Android NFC nemajú.
• accept-nfc-sunmi pridá oprávnenie com.sunmi.perm.CONTACTLESS_CARD a záznam <queries> pre platobnú službu Sunmi. Obsahuje knižnicu Sunmi PayLib.

Integrácia

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
    }
}

Spracovanie chýb

Zlyhania pri práci s tagom vyhadzujú TagSessionException, ktorej reason vám povie, čo robiť ďalej. Volanie API pred nastavením SDK vyhodí NotInitialized. TagSessionException nie je AcceptException, preto tieto dve výnimky zachytávajte oddelene:

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
}

Ak má argument kľúča, bloku alebo stránky nesprávnu dĺžku alebo znamienko, prípadne je rámec alebo APDU prázdne, vyhodí sa IllegalArgumentException skôr, než sa čokoľvek dostane k tagu.

Otváranie relácie

Odoslanie príkazu

Relácia skončila

Časové limity

Ak chcete zmeniť predvolené hodnoty, odovzdajte openSession() objekt TagTimeouts:

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

Každá hodnota musí byť väčšia ako nula. Vytvorenie TagTimeouts s hodnotou mimo týchto rozsahov vyhodí IllegalArgumentException.

Dobré vedieť

• Jedna čítačka. Zariadenie má jednu bezkontaktnú čítačku, takže naraz môže prebiehať len jedna relácia s tagom alebo jedno čakanie na priloženie. Druhé volanie openSession() zlyhá s READER_BUSY. Platby spustené cez Accept.payments.pay() reláciu najprv ukončia; platby spustené mimo SDK sa koordinovať nedajú, preto udržiavajte relácie krátke.
• Zrušenie príkazu ho nevráti späť. V okamihu, keď korutinu zrušíte, príkaz už dorazil k tagu a stále sa vykonáva; zahodí sa len jeho výsledok. Zrušený writeBlock teda môže tag aj tak zmeniť.
• Príkazy sa vykonávajú v poradí. Metódy relácie možno volať z ľubovoľnej korutiny; k tagu sa dostávajú jedna po druhej, v poradí, v akom ich voláte.
• Údaje tagov sa nedostanú do logov. SDK nikdy neloguje kľúče, heslá ani údaje tagov a UID maskuje (napr. 04A1…E5F6). Ako vaša aplikácia údaje tagov ukladá a zobrazuje, je na vás.

Otestovanie integrácie

Na telefóne a, ak ich podporujete, aj na termináli Sunmi radu P:

1. Overte, že isSupported() vracia true na oboch a false na zariadení bez NFC.
2. Priložte tag NTAG alebo Ultralight a overte, že relácia hlási správne UID a readPages(0) vracia 16 bajtov. Potom vykonajte writePage a stránku znova prečítajte.
3. Na karte MIFARE Classic vykonajte autentifikáciu nesprávnym kľúčom a potvrďte AUTH_FAILED, potom správnym kľúčom.
4. Zrušte openSession() počas čakania na priloženie a hneď otvorte novú reláciu.
5. Počas relácie spustite platbu: relácia by mala skončiť ako PAYMENT a platba by mala prejsť. Počas inej relácie tag oddiaľte: relácia by mala skončiť ako CARD_REMOVED.
6. Na telefóne vypnite NFC a potvrďte NFC_DISABLED. Počas relácie pošlite aplikáciu na pozadie a potvrďte, že relácia skončí ako ACTIVITY_PAUSED.