NFC-Tags

Lesen und beschreiben Sie NFC-Tags wie Kundenkarten, Zutrittsausweise, Sticker und Chipkarten direkt in Ihrer Android-App. Das SDK kommuniziert mit dem geräteeigenen Lesegerät: mit Android NFC auf einem Telefon oder mit dem kontaktlosen Lesegerät eines Terminals der Sunmi-P-Serie. Dazwischen ist kein Plugin geschaltet.

Tag-Sessions werden in optionalen Artefakten ausgeliefert: com.tapaya:accept-nfc und, für Sunmi-Terminals, com.tapaya:accept-nfc-sunmi. Fügen Sie sie nur hinzu, wenn Sie sie benötigen; Kartenzahlungen funktionieren mit und ohne sie gleich.

Unterstützte Geräte

Terminals der Sunmi-P-Serie haben kein Android NFC; ihre Antenne sitzt hinter dem Zahlungsmodul. accept-nfc-sunmi erreicht sie über den Zahlungsdienst von Sunmi und tritt an die Stelle von Android NFC, wann immer dieser Dienst installiert ist.

Auf einem Gerät ohne nutzbares Lesegerät gibt isSupported() den Wert false zurück, und openSession() schlägt mit NOT_SUPPORTED fehl.

Unterstützte Tags

So funktioniert es

1. Ihre App ruft Accept.nfc.openSession(activity) auf.
2. Das SDK schaltet das Lesegerät des Geräts ein und wartet darauf, dass ein Tag vorgehalten wird.
3. Der Kunde hält einen Tag vor, und openSession() gibt eine TagSession mit der UID und der Familie des Tags zurück.
4. Ihre App liest und schreibt über die Session, jeweils einen Befehl nach dem anderen.
5. Ihre App ruft close() auf und gibt damit das Lesegerät für Zahlungen und andere Tag-Sessions frei.

Voraussetzungen

• Ein unterstütztes Gerät.
• Das Accept SDK ist installiert und initialisiert. Wenn Sie isSupported() oder openSession() vor Accept.initialize aufrufen, wird NotInitialized geworfen.

Tag-Sessions benötigen keinen angemeldeten Händler, kein Tapaya-Terminal-Plugin und keine Standortberechtigung. Die Artefakte ergänzen Ihr Manifest um alles, was sie benötigen:

• accept-nfc fügt die Berechtigung NFC hinzu und kennzeichnet android.hardware.nfc als nicht erforderlich, sodass Google Play Ihre App auch auf Sunmi-Terminals verfügbar hält, die kein Android NFC haben.
• accept-nfc-sunmi fügt die Berechtigung com.sunmi.perm.CONTACTLESS_CARD und einen <queries>-Eintrag für den Zahlungsdienst von Sunmi hinzu. Es bettet Sunmi PayLib ein.

Integration

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

Fehlerbehandlung

Bei Fehlern am Tag wird eine TagSessionException geworfen, deren reason Ihnen sagt, was als Nächstes zu tun ist. Wird die API aufgerufen, bevor das SDK eingerichtet ist, wird NotInitialized geworfen. TagSessionException ist keine AcceptException, fangen Sie die beiden daher getrennt ab:

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
}

Ein Schlüssel-, Block- oder Seitenargument mit falscher Länge oder falschem Vorzeichen oder ein leerer Frame bzw. eine leere APDU wirft eine IllegalArgumentException, bevor irgendetwas den Tag erreicht.

Beim Öffnen einer Session

Beim Senden eines Befehls

Session beendet

Timeouts

Übergeben Sie TagTimeouts an openSession(), um die Standardwerte zu ändern:

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

Jeder Wert muss größer als null sein. Wird TagTimeouts mit einem Wert außerhalb dieser Bereiche erstellt, wird eine IllegalArgumentException geworfen.

Gut zu wissen

• Ein einziges Lesegerät. Das Gerät hat ein einziges kontaktloses Lesegerät, daher ist jeweils nur eine Tag-Session oder ein ausstehendes Warten auf das Vorhalten möglich. Ein zweiter Aufruf von openSession() schlägt mit READER_BUSY fehl. Zahlungen, die mit Accept.payments.pay() gestartet werden, beenden zuerst eine Session; Zahlungen, die außerhalb des SDK gestartet werden, lassen sich nicht koordinieren, halten Sie Sessions daher kurz.
• Das Abbrechen eines Befehls macht ihn nicht rückgängig. Wenn Sie die Coroutine abbrechen, hat der Befehl den Tag bereits erreicht und wird weiter ausgeführt; nur sein Ergebnis wird verworfen. Ein abgebrochenes writeBlock kann den Tag also trotzdem verändern.
• Befehle werden der Reihe nach ausgeführt. Session-Methoden können aus jeder Coroutine aufgerufen werden; sie erreichen den Tag einzeln, in der Reihenfolge Ihrer Aufrufe.
• Tag-Daten gelangen nicht in Logs. Das SDK protokolliert nie Schlüssel, Passwörter oder Tag-Daten und maskiert UIDs (z. B. 04A1…E5F6). Wie Ihre App Tag-Daten speichert und anzeigt, liegt bei Ihnen.

Integration testen

Auf einem Telefon und, falls Sie diese unterstützen, auf einem Terminal der Sunmi-P-Serie:

1. Prüfen Sie, dass isSupported() auf beiden true und auf einem Gerät ohne NFC false zurückgibt.
2. Halten Sie einen NTAG- oder Ultralight-Tag vor und prüfen Sie, dass die Session die richtige UID meldet und readPages(0) 16 Byte zurückgibt. Führen Sie dann writePage aus und lesen Sie die Seite erneut.
3. Authentifizieren Sie sich bei MIFARE Classic mit einem falschen Schlüssel und bestätigen Sie AUTH_FAILED, dann mit dem richtigen.
4. Brechen Sie openSession() während des Wartens auf das Vorhalten ab und öffnen Sie sofort eine neue Session.
5. Starten Sie während einer Session eine Zahlung: Die Session sollte als PAYMENT enden und die Zahlung durchgehen. Entfernen Sie während einer anderen Session den Tag: Sie sollte als CARD_REMOVED enden.
6. Schalten Sie auf einem Telefon NFC aus und bestätigen Sie NFC_DISABLED. Schicken Sie die App während einer Session in den Hintergrund und bestätigen Sie, dass die Session als ACTIVITY_PAUSED endet.