Tags NFC

Lisez et écrivez des tags NFC, tels que des cartes de fidélité, des badges d’accès, des autocollants et des cartes à puce, directement depuis votre application Android. Le SDK communique avec le lecteur propre à l’appareil : le NFC Android sur un téléphone, ou le lecteur sans contact d’un terminal Sunmi de la série P. Aucun plugin ne sert d’intermédiaire.

Les sessions de tag sont fournies dans des artefacts facultatifs, com.tapaya:accept-nfc et, pour les terminaux Sunmi, com.tapaya:accept-nfc-sunmi. Ajoutez-les uniquement si vous en avez besoin ; les paiements par carte fonctionnent de la même manière avec ou sans eux.

Appareils pris en charge

Les terminaux Sunmi de la série P n’ont pas de NFC Android ; leur antenne se trouve derrière le module de paiement. accept-nfc-sunmi y accède via le service de paiement de Sunmi et prend le relais du NFC Android dès que ce service est installé.

Sur un appareil sans lecteur utilisable, isSupported() renvoie false et openSession() échoue avec NOT_SUPPORTED.

Tags pris en charge

Fonctionnement

1. Votre application appelle Accept.nfc.openSession(activity).
2. Le SDK active le lecteur de l’appareil et attend une présentation.
3. Le client approche un tag, et openSession() renvoie une TagSession contenant l’UID et la famille du tag.
4. Votre application lit et écrit via la session, une commande à la fois.
5. Votre application appelle close(), ce qui libère le lecteur pour les paiements et les autres sessions de tag.

Prérequis

• Un appareil pris en charge.
• L’Accept SDK installé et initialisé. Appeler isSupported() ou openSession() avant Accept.initialize lève NotInitialized.

Les sessions de tag ne nécessitent ni commerçant connecté, ni plugin Tapaya Terminal, ni autorisation de localisation. Les artefacts ajoutent à votre manifeste ce dont ils ont besoin :

• accept-nfc ajoute l’autorisation NFC et déclare android.hardware.nfc comme non obligatoire, afin que Play laisse votre application disponible sur les terminaux Sunmi, qui n’ont pas de NFC Android.
• accept-nfc-sunmi ajoute l’autorisation com.sunmi.perm.CONTACTLESS_CARD et une entrée <queries> pour le service de paiement de Sunmi. Il intègre Sunmi PayLib.

Intégration

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

Gestion des erreurs

Les échecs liés au tag lèvent TagSessionException, dont le reason vous indique quoi faire ensuite. Appeler l’API avant que le SDK ne soit configuré lève NotInitialized. TagSessionException n’est pas une AcceptException ; interceptez donc les deux séparément :

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 argument de clé, de bloc ou de page dont la longueur ou le signe est incorrect, ou une trame ou une APDU vide, lève IllegalArgumentException avant que quoi que ce soit n’atteigne le tag.

Ouverture d’une session

Envoi d’une commande

Session terminée

Délais d’expiration

Transmettez TagTimeouts à openSession() pour modifier les valeurs par défaut :

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

Chaque valeur doit être supérieure à zéro. Construire TagTimeouts avec une valeur hors de ces plages lève IllegalArgumentException.

Bon à savoir

• Un seul lecteur. L’appareil dispose d’un seul lecteur sans contact, d’où une seule session de tag ou attente de présentation à la fois. Un second openSession() échoue avec READER_BUSY. Les paiements démarrés avec Accept.payments.pay() mettent d’abord fin à la session ; les paiements démarrés en dehors du SDK ne peuvent pas être coordonnés, gardez donc les sessions courtes.
• Annuler une commande ne l’annule pas sur le tag. Au moment où vous annulez la coroutine, la commande a déjà atteint le tag et s’exécute quand même ; seul son résultat est ignoré. Un writeBlock annulé peut donc tout de même modifier le tag.
• Les commandes s’exécutent dans l’ordre. Les méthodes de session peuvent être appelées depuis n’importe quelle coroutine ; elles atteignent le tag une par une, dans l’ordre de vos appels.
• Les données de tag restent hors des logs. Le SDK ne journalise jamais les clés, les mots de passe ni les données de tag, et masque les UID (par exemple 04A1…E5F6). La manière dont votre application stocke et affiche les données de tag relève de votre responsabilité.

Tester l’intégration

Sur un téléphone et, si vous les prenez en charge, sur un terminal Sunmi de la série P :

1. Vérifiez que isSupported() renvoie true sur les deux, et false sur un appareil sans NFC.
2. Présentez un tag NTAG ou Ultralight et vérifiez que la session indique le bon UID et que readPages(0) renvoie 16 octets. Puis exécutez writePage et relisez la page.
3. Sur une carte MIFARE Classic, authentifiez-vous avec une clé erronée et vérifiez que vous obtenez AUTH_FAILED, puis avec la bonne clé.
4. Annulez openSession() pendant l’attente de présentation et ouvrez immédiatement une nouvelle session.
5. Démarrez un paiement pendant une session : la session doit se terminer en PAYMENT et le paiement doit aboutir. Retirez le tag pendant une autre session : celle-ci doit se terminer en CARD_REMOVED.
6. Sur un téléphone, désactivez le NFC et vérifiez que vous obtenez NFC_DISABLED. Pendant une session, mettez l’application en arrière-plan et vérifiez que la session se termine en ACTIVITY_PAUSED.