NFC tagy

Čtěte a zapisujte NFC tagy, například věrnostní karty, přístupové karty, nálepky a čipové karty, přímo ze své aplikace pro Android. SDK komunikuje přímo s čtečkou zařízení: na telefonu s Android NFC, na terminálu Sunmi řady P s jeho bezkontaktní čtečkou. Mezi SDK a čtečkou nestojí žádný plugin.

Relace s tagy jsou součástí volitelných artefaktů com.tapaya:accept-nfc a pro terminály Sunmi com.tapaya:accept-nfc-sunmi. Přidejte je jen tehdy, když je potřebujete; platby kartou fungují s nimi i bez nich stejně.

Podporovaná zařízení

Terminály Sunmi řady P nemají Android NFC; jejich anténa je umístěna za platebním modulem. accept-nfc-sunmi k ní přistupuje přes platební službu Sunmi, a kdykoli je tato služba nainstalovaná, má přednost před Android NFC.

Na zařízení bez použitelné čtečky vrací isSupported() hodnotu false a openSession() selže s NOT_SUPPORTED.

Podporované tagy

Jak to funguje

1. Vaše aplikace zavolá Accept.nfc.openSession(activity).
2. SDK zapne čtečku zařízení a čeká na přiložení.
3. Zákazník přiloží tag a openSession() vrátí TagSession s UID a rodinou tagu.
4. Vaše aplikace čte a zapisuje prostřednictvím relace, vždy po jednom příkazu.
5. Vaše aplikace zavolá close(), čímž uvolní čtečku pro platby a další relace s tagy.

Předpoklady

• Podporované zařízení.
• Accept SDK nainstalované a inicializované. Volání isSupported() nebo openSession() před Accept.initialize vyhodí NotInitialized.

Relace s tagy nevyžadují přihlášeného obchodníka, plugin Tapaya Terminal ani oprávnění k poloze. Artefakty si do vašeho manifestu přidají, co potřebují:

• accept-nfc přidá oprávnění NFC a označí android.hardware.nfc jako nepovinné, takže Google Play ponechá vaši aplikaci dostupnou i na terminálech Sunmi, které Android NFC nemají.
• accept-nfc-sunmi přidá oprávnění com.sunmi.perm.CONTACTLESS_CARD a záznam <queries> pro platební službu Sunmi. Obsahuje knihovnu Sunmi PayLib.

Integrace

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

Zpracování chyb

Selhání při práci s tagem vyhazují TagSessionException, jejíž reason vám řekne, co dělat dál. Volání API dřív, než je SDK nastavené, vyhodí NotInitialized. TagSessionException není AcceptException, proto je zachytávejte zvlášť:

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
}

Pokud má argument klíče, bloku nebo stránky nesprávnou délku nebo znaménko, případně je rámec nebo APDU prázdné, vyhodí se IllegalArgumentException dřív, než se cokoli dostane k tagu.

Otevírání relace

Odeslání příkazu

Relace skončila

Časové limity

Chcete-li změnit výchozí hodnoty, předejte openSession() objekt TagTimeouts:

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

Každá hodnota musí být větší než nula. Vytvoření TagTimeouts s hodnotou mimo tyto rozsahy vyhodí IllegalArgumentException.

Dobré vědět

• Jedna čtečka. Zařízení má jednu bezkontaktní čtečku, takže najednou může běžet jen jedna relace s tagem nebo jedno čekání na přiložení. Druhé volání openSession() selže s READER_BUSY. Platby zahájené pomocí Accept.payments.pay() relaci nejprve ukončí; platby zahájené mimo SDK koordinovat nelze, proto relace udržujte krátké.
• Zrušení příkazu jej nevrátí zpět. V okamžiku, kdy korutinu zrušíte, už příkaz dorazil k tagu a stále se provádí; zahodí se jen jeho výsledek. Zrušený writeBlock tedy může tag přesto změnit.
• Příkazy se provádějí v pořadí. Metody relace lze volat z libovolné korutiny; k tagu se dostávají jedna po druhé, v pořadí, v jakém je voláte.
• Data tagů se nedostanou do logů. SDK nikdy neloguje klíče, hesla ani data tagů a UID maskuje (např. 04A1…E5F6). Jak vaše aplikace data tagů ukládá a zobrazuje, je na vás.

Otestování integrace

Na telefonu a, pokud je podporujete, na terminálu Sunmi řady P:

1. Ověřte, že isSupported() vrací true na obou zařízeních a false na zařízení bez NFC.
2. Přiložte tag NTAG nebo Ultralight a ověřte, že relace hlásí správné UID a readPages(0) vrací 16 bajtů. Poté proveďte writePage a stránku znovu přečtěte.
3. Na kartě MIFARE Classic se autentizujte nesprávným klíčem a potvrďte AUTH_FAILED, pak správným klíčem.
4. Zrušte openSession() během čekání na přiložení a ihned otevřete novou relaci.
5. Během relace zahajte platbu: relace by měla skončit jako PAYMENT a platba by měla projít. Během jiné relace tag oddalte: relace by měla skončit jako CARD_REMOVED.
6. Na telefonu vypněte NFC a potvrďte NFC_DISABLED. Během relace přesuňte aplikaci na pozadí a potvrďte, že relace skončí jako ACTIVITY_PAUSED.