NFC Mobile SDK

Build native mobile apps that scan and verify TAG IT NFC tags.

Supported Platforms

The TAG IT NFC Mobile SDK supports the following platforms:

• iOS 13+ - Full NFC tag reading and writing support via Core NFC
• Android 5.0+ (API Level 21) - NFC support via Android NFC API

Installation

Choose your platform below to get started with the SDK installation.

iOS Installation

Install the SDK using CocoaPods or Swift Package Manager:

CocoaPods

# Add to your Podfile
pod 'TagItNFC', '~> 2.0'

# Then run
pod install

Swift Package Manager

// In Xcode: File > Add Packages
// Enter the repository URL:
// https://github.com/TAG-IT-NETWORK/tagit-nfc-ios

// Or add to Package.swift:
dependencies: [
    .package(url: "https://github.com/TAG-IT-NETWORK/tagit-nfc-ios", from: "2.0.0")
]

Android Installation

Add the SDK to your project via Gradle:

// Add to your app's build.gradle
dependencies {
    implementation 'network.tagit:nfc-sdk:2.0.0'
}

// Add to your project's build.gradle (if using JitPack)
repositories {
    maven { url 'https://jitpack.io' }
}

Permissions & Entitlements

Configure the required permissions for each platform:

iOS (Info.plist)

<key>NFCReaderUsageDescription</key>
<string>This app uses NFC to scan and verify product authenticity.</string>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>D2760000850101</string>
</array>

You must also enable the Near Field Communication Tag Reading capability in your app's entitlements.

Android (AndroidManifest.xml)

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="true" />

<!-- Optional: Launch app when NFC tag is discovered -->
<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="application/vnd.tagit.nfc" />
</intent-filter>

Scanning NFC Tags

Learn how to implement NFC tag scanning on each platform.

iOS Implementation

Use the TagItNFC framework to scan tags in your Swift application:

import TagItNFC

class NFCViewController: UIViewController {

    private let tagItScanner = TagItNFCScanner()

    override func viewDidLoad() {
        super.viewDidLoad()

        // Configure the scanner
        tagItScanner.configure(
            apiKey: "your_api_key",
            environment: .production
        )
    }

    @IBAction func scanButtonTapped(_ sender: UIButton) {
        // Check NFC availability
        guard tagItScanner.isNFCAvailable else {
            showAlert(message: "NFC is not available on this device")
            return
        }

        // Start scanning session
        tagItScanner.startScanning { [weak self] result in
            DispatchQueue.main.async {
                switch result {
                case .success(let tag):
                    self?.handleScannedTag(tag)
                case .failure(let error):
                    self?.handleScanError(error)
                }
            }
        }
    }

    private func handleScannedTag(_ tag: TagItTag) {
        print("Tag ID: \(tag.identifier)")
        print("Product: \(tag.productName ?? "Unknown")")
        print("Verified: \(tag.isVerified)")

        // Navigate to product details
        let detailVC = ProductDetailViewController(tag: tag)
        navigationController?.pushViewController(detailVC, animated: true)
    }

    private func handleScanError(_ error: TagItError) {
        switch error {
        case .sessionCancelled:
            // User cancelled - no action needed
            break
        case .tagNotFound:
            showAlert(message: "No TAG IT tag detected")
        case .invalidTag:
            showAlert(message: "This tag is not a valid TAG IT tag")
        case .networkError(let underlying):
            showAlert(message: "Network error: \(underlying.localizedDescription)")
        default:
            showAlert(message: "Scan failed: \(error.localizedDescription)")
        }
    }
}

Android Implementation

Implement NFC scanning in your Kotlin Android application:

import network.tagit.nfc.TagItNFCScanner
import network.tagit.nfc.TagItTag
import network.tagit.nfc.TagItError
import network.tagit.nfc.Environment

class NFCScanActivity : AppCompatActivity() {

    private lateinit var tagItScanner: TagItNFCScanner

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_nfc_scan)

        // Initialize the scanner
        tagItScanner = TagItNFCScanner.Builder(this)
            .setApiKey("your_api_key")
            .setEnvironment(Environment.PRODUCTION)
            .build()

        // Set up scan button
        findViewById<Button>(R.id.scanButton).setOnClickListener {
            startNFCScan()
        }
    }

    override fun onResume() {
        super.onResume()
        tagItScanner.enableForegroundDispatch(this)
    }

    override fun onPause() {
        super.onPause()
        tagItScanner.disableForegroundDispatch(this)
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        intent?.let { handleNFCIntent(it) }
    }

    private fun startNFCScan() {
        if (!tagItScanner.isNFCAvailable()) {
            showToast("NFC is not available on this device")
            return
        }

        if (!tagItScanner.isNFCEnabled()) {
            // Prompt user to enable NFC
            startActivity(Intent(Settings.ACTION_NFC_SETTINGS))
            return
        }

        showToast("Hold your device near a TAG IT tag")
    }

    private fun handleNFCIntent(intent: Intent) {
        tagItScanner.processIntent(intent) { result ->
            runOnUiThread {
                result.fold(
                    onSuccess = { tag -> handleScannedTag(tag) },
                    onFailure = { error -> handleScanError(error) }
                )
            }
        }
    }

    private fun handleScannedTag(tag: TagItTag) {
        Log.d("NFC", "Tag ID: ${tag.identifier}")
        Log.d("NFC", "Product: ${tag.productName}")
        Log.d("NFC", "Verified: ${tag.isVerified}")

        // Navigate to product details
        val intent = Intent(this, ProductDetailActivity::class.java).apply {
            putExtra("tag", tag)
        }
        startActivity(intent)
    }

    private fun handleScanError(error: Throwable) {
        val message = when (error) {
            is TagItError.TagNotFound -> "No TAG IT tag detected"
            is TagItError.InvalidTag -> "This tag is not a valid TAG IT tag"
            is TagItError.NetworkError -> "Network error: ${error.message}"
            else -> "Scan failed: ${error.message}"
        }
        showToast(message)
    }
}

Verifying Tags

After scanning a tag, verify its authenticity against the blockchain:

// iOS - Swift
func verifyTag(_ tag: TagItTag) async throws -> VerificationResult {
    let verifier = TagItVerifier(apiKey: "your_api_key")

    let result = try await verifier.verify(
        tagId: tag.identifier,
        options: VerificationOptions(
            checkBlockchain: true,
            includeHistory: true,
            includeMetadata: true
        )
    )

    return result
}

// Android - Kotlin
suspend fun verifyTag(tag: TagItTag): VerificationResult {
    val verifier = TagItVerifier.Builder(context)
        .setApiKey("your_api_key")
        .build()

    return verifier.verify(
        tagId = tag.identifier,
        options = VerificationOptions(
            checkBlockchain = true,
            includeHistory = true,
            includeMetadata = true
        )
    )
}

UI Components

The SDK includes pre-built UI components for a seamless scanning experience:

// iOS - Present the built-in scanner UI
let scannerVC = TagItScannerViewController()
scannerVC.delegate = self
scannerVC.theme = .dark // or .light, .system
scannerVC.instructionText = "Hold your iPhone near the product tag"
present(scannerVC, animated: true)

// Android - Launch the built-in scanner activity
val intent = TagItScannerActivity.createIntent(
    context = this,
    theme = TagItTheme.DARK, // or LIGHT, SYSTEM
    instructionText = "Hold your phone near the product tag"
)
startActivityForResult(intent, SCAN_REQUEST_CODE)

Available UI components include:

• Scanner View - Full-screen NFC scanning interface with animations
• Verification Card - Display verification results with product details
• History List - Show ownership transfer history
• Error Views - Pre-styled error states for common issues

Troubleshooting

Common issues and their solutions:

Device Compatibility

• iOS: NFC reading requires iPhone 7 or later. Background tag reading requires iPhone XS or later.
• Android: Ensure the device has NFC hardware. Some budget devices may not include NFC.

Common Errors

• "NFC not available" - The device doesn't support NFC or the feature is disabled in settings.
• "Session invalidated" - On iOS, NFC sessions timeout after 60 seconds. Restart the scan.
• "Tag not supported" - The scanned tag is not a TAG IT NFC tag. Verify you're scanning the correct product.
• "Network error" - Check internet connectivity. The SDK requires network access for verification.
• "Invalid API key" - Verify your API key is correct and has mobile SDK permissions enabled.