NFC-мітки

Зчитуйте й записуйте NFC-мітки, як-от картки лояльності, перепустки, наліпки та смарт-картки, безпосередньо зі свого застосунку для Android. SDK працює із власним зчитувачем пристрою: з Android NFC на телефоні або з безконтактним зчитувачем термінала Sunmi серії P. Жодного плагіна між ними немає.

Сесії з мітками постачаються в необов'язкових артефактах: com.tapaya:accept-nfc і, для терміналів Sunmi, com.tapaya:accept-nfc-sunmi. Додавайте їх, лише якщо вони вам потрібні; платежі карткою працюють однаково з ними і без них.

Підтримувані пристрої

Термінали Sunmi серії P не мають Android NFC; їхня антена розташована за платіжним модулем. accept-nfc-sunmi звертається до неї через платіжний сервіс Sunmi і замінює Android NFC щоразу, коли цей сервіс установлено.

На пристрої без придатного зчитувача isSupported() повертає false, а openSession() завершується помилкою NOT_SUPPORTED.

Підтримувані мітки

Як це працює

1. Ваш застосунок викликає Accept.nfc.openSession(activity).
2. SDK вмикає зчитувач пристрою і чекає на прикладання.
3. Клієнт прикладає мітку, і openSession() повертає TagSession з UID і сімейством мітки.
4. Ваш застосунок зчитує й записує дані через сесію, по одній команді за раз.
5. Ваш застосунок викликає close(), що звільняє зчитувач для платежів та інших сесій з мітками.

Передумови

• Підтримуваний пристрій.
• Accept SDK установлено й ініціалізовано. Виклик isSupported() або openSession() до Accept.initialize викидає NotInitialized.

Сесії з мітками не потребують мерчанта, який увійшов у застосунок, плагіна Tapaya Terminal чи дозволу на доступ до геолокації. Артефакти самі додають до вашого маніфесту все потрібне:

• accept-nfc додає дозвіл NFC і позначає функцію android.hardware.nfc як необов'язкову, тож Play залишає ваш застосунок доступним на терміналах Sunmi, які не мають Android NFC.
• accept-nfc-sunmi додає дозвіл com.sunmi.perm.CONTACTLESS_CARD і запис <queries> для платіжного сервісу Sunmi. Він містить вбудовану бібліотеку Sunmi PayLib.

Інтеграція

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

Обробка помилок

Збої під час роботи з міткою викидають TagSessionException, чий reason підказує, що робити далі. Виклик API до налаштування SDK викидає NotInitialized. TagSessionException не є AcceptException, тому перехоплюйте ці два винятки окремо:

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
}

Аргумент ключа, блоку чи сторінки неправильної довжини або знака, а також порожній кадр чи APDU, спричиняють IllegalArgumentException ще до того, як будь-що дійде до мітки.

Відкриття сесії

Надсилання команди

Сесію завершено

Тайм-аути

Щоб змінити значення за замовчуванням, передайте TagTimeouts в openSession():

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

Кожне значення має бути більшим за нуль. Створення TagTimeouts зі значенням поза цими діапазонами викидає IllegalArgumentException.

Корисно знати

• Один зчитувач. Пристрій має один безконтактний зчитувач, тому одночасно можлива лише одна сесія з міткою або одне очікування прикладання. Другий виклик openSession() завершується помилкою READER_BUSY. Платежі, розпочаті через Accept.payments.pay(), спершу завершують сесію; платежі, розпочаті поза SDK, узгодити неможливо, тому робіть сесії короткими.
• Скасування команди не відміняє її. На момент, коли ви скасовуєте корутину, команда вже дійшла до мітки й усе одно виконується; відкидається лише її результат. Скасований writeBlock усе ще може змінити мітку.
• Команди виконуються по черзі. Методи сесії можна викликати з будь-якої корутини; вони доходять до мітки по одній, у тому порядку, у якому ви їх викликаєте.
• Дані міток не потрапляють у логи. SDK ніколи не записує в логи ключі, паролі чи дані міток і маскує UID (наприклад, 04A1…E5F6). Як ваш застосунок зберігає й показує дані міток, вирішуєте ви.

Тестування інтеграції

На телефоні та, якщо ви їх підтримуєте, на терміналі Sunmi серії P:

1. Перевірте, що isSupported() повертає true на обох пристроях і false на пристрої без NFC.
2. Прикладіть мітку NTAG або Ultralight і перевірте, що сесія повідомляє правильний UID, а readPages(0) повертає 16 байтів. Потім виконайте writePage і зчитайте сторінку знову.
3. На MIFARE Classic пройдіть автентифікацію неправильним ключем і переконайтеся, що отримано AUTH_FAILED, а потім правильним.
4. Скасуйте openSession() під час очікування прикладання й одразу відкрийте нову сесію.
5. Почніть платіж під час сесії: сесія має завершитися як PAYMENT, а платіж має пройти. Заберіть мітку під час іншої сесії: сесія має завершитися як CARD_REMOVED.
6. На телефоні вимкніть NFC і переконайтеся, що отримано NFC_DISABLED. Під час сесії переведіть застосунок у фоновий режим і переконайтеся, що сесія завершується як ACTIVITY_PAUSED.