Tag NFC

Đọc và ghi tag NFC, chẳng hạn thẻ khách hàng thân thiết, thẻ ra vào, nhãn dán và thẻ thông minh, trực tiếp từ ứng dụng Android của bạn. SDK giao tiếp với chính đầu đọc của thiết bị: Android NFC trên điện thoại, hoặc đầu đọc không tiếp xúc của máy thanh toán Sunmi dòng P. Không có plugin nào đứng giữa.

Phiên đọc tag được cung cấp trong các artifact tùy chọn, com.tapaya:accept-nfc và, cho máy Sunmi, com.tapaya:accept-nfc-sunmi. Chỉ thêm các artifact này nếu bạn cần; thanh toán bằng thẻ vẫn hoạt động như nhau dù có hay không có chúng.

Thiết bị được hỗ trợ

Máy thanh toán Sunmi dòng P không có Android NFC; ăng-ten của chúng nằm phía sau mô-đun thanh toán. accept-nfc-sunmi truy cập ăng-ten này thông qua dịch vụ thanh toán của Sunmi, và được dùng thay cho Android NFC bất cứ khi nào dịch vụ đó được cài đặt.

Trên thiết bị không có đầu đọc dùng được, isSupported() trả về false và openSession() thất bại với NOT_SUPPORTED.

Tag được hỗ trợ

Cách hoạt động

1. Ứng dụng của bạn gọi Accept.nfc.openSession(activity).
2. SDK bật đầu đọc của thiết bị và chờ chạm tag.
3. Khách hàng chạm một tag, và openSession() trả về một TagSession mang UID và họ (family) của tag.
4. Ứng dụng của bạn đọc và ghi thông qua phiên, mỗi lần một lệnh.
5. Ứng dụng của bạn gọi close(), thao tác này giải phóng đầu đọc cho thanh toán và các phiên đọc tag khác.

Điều kiện tiên quyết

• Một thiết bị được hỗ trợ.
• Accept SDK đã được cài đặt và khởi tạo. Gọi isSupported() hoặc openSession() trước Accept.initialize sẽ ném ra NotInitialized.

Phiên đọc tag không cần merchant đã đăng nhập, plugin Tapaya Terminal hay quyền truy cập vị trí. Các artifact tự thêm những gì chúng cần vào manifest của bạn:

• accept-nfc thêm quyền NFC và đánh dấu android.hardware.nfc là không bắt buộc, để Play vẫn cung cấp ứng dụng của bạn trên máy Sunmi, vốn không có Android NFC.
• accept-nfc-sunmi thêm quyền com.sunmi.perm.CONTACTLESS_CARD và một mục <queries> cho dịch vụ thanh toán của Sunmi. Artifact này nhúng sẵn Sunmi PayLib.

Tích hợp

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

Xử lý lỗi

Lỗi liên quan tới tag sẽ ném ra TagSessionException, với reason cho bạn biết cần làm gì tiếp theo. Gọi API trước khi SDK được thiết lập sẽ ném ra NotInitialized. TagSessionException không phải là một AcceptException, vì vậy hãy bắt riêng hai loại này:

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
}

Đối số khóa, block hoặc trang có độ dài hoặc dấu không đúng, hoặc frame hay APDU rỗng, sẽ ném ra IllegalArgumentException trước khi bất cứ thứ gì đến được tag.

Mở phiên

Gửi lệnh

Phiên đã kết thúc

Thời gian chờ

Truyền TagTimeouts vào openSession() để thay đổi giá trị mặc định:

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

Mọi giá trị đều phải lớn hơn 0. Tạo TagTimeouts với giá trị nằm ngoài các khoảng này sẽ ném ra IllegalArgumentException.

Cần lưu ý

• Một đầu đọc. Thiết bị chỉ có một đầu đọc không tiếp xúc, nên mỗi lúc chỉ có một phiên đọc tag hoặc một lượt chờ chạm. Lệnh gọi openSession() thứ hai sẽ thất bại với READER_BUSY. Khoản thanh toán bắt đầu bằng Accept.payments.pay() sẽ kết thúc phiên trước; khoản thanh toán bắt đầu bên ngoài SDK thì không thể điều phối, vì vậy hãy giữ phiên ngắn gọn.
• Hủy một lệnh không hoàn tác lệnh đó. Vào lúc bạn hủy coroutine, lệnh đã tới tag và vẫn được thực thi; chỉ kết quả của nó bị bỏ đi. Một writeBlock đã bị hủy vẫn có thể thay đổi tag.
• Các lệnh chạy theo thứ tự. Có thể gọi các phương thức của phiên từ bất kỳ coroutine nào; chúng tới tag lần lượt từng lệnh một, theo đúng thứ tự bạn gọi.
• Dữ liệu tag không xuất hiện trong log. SDK không bao giờ ghi log khóa, mật khẩu hay dữ liệu tag, và che UID (ví dụ 04A1…E5F6). Việc ứng dụng của bạn lưu trữ và hiển thị dữ liệu tag như thế nào là do bạn quyết định.

Kiểm thử tích hợp

Trên điện thoại và, nếu bạn hỗ trợ, trên máy thanh toán Sunmi dòng P:

1. Kiểm tra rằng isSupported() trả về true trên cả hai, và false trên thiết bị không có NFC.
2. Chạm một tag NTAG hoặc Ultralight và xác minh rằng phiên báo đúng UID và readPages(0) trả về 16 byte. Sau đó thực hiện writePage và đọc lại trang đó.
3. Trên MIFARE Classic, xác thực bằng một khóa sai và xác nhận nhận được AUTH_FAILED, sau đó xác thực bằng khóa đúng.
4. Hủy openSession() trong lúc chờ chạm và mở ngay một phiên mới.
5. Bắt đầu một khoản thanh toán trong khi phiên đang mở: phiên sẽ kết thúc với PAYMENT và khoản thanh toán được thực hiện thành công. Lấy tag ra trong một phiên khác: phiên sẽ kết thúc với CARD_REMOVED.
6. Trên điện thoại, tắt NFC và xác nhận nhận được NFC_DISABLED. Trong khi phiên đang mở, đưa ứng dụng xuống chạy nền và xác nhận phiên kết thúc với ACTIVITY_PAUSED.