For the complete documentation index, see llms.txt. This page is also available as Markdown.

πŸ’³NFC

Read and write NFC tags directly from your app using native NFC capabilities.

What is NFC?

NFC (Near Field Communication) lets your app interact with NFC tags - small chips embedded in cards, stickers, or objects. Your app can read data from NFC tags or write data to them, enabling use cases like contactless check-ins, product authentication, smart packaging, loyalty cards, and more.

Prerequisites

iOS only:

App Capabilities Configuration (iOS only)

App capabilities define what system-level features your app is allowed to use on iOS. Before Natively can include the NFC feature in your iOS build, the NFC Tag Reading capability must be explicitly enabled in your Apple Developer account for your app's Bundle ID.

  1. Select your app's Bundle ID.

  2. Scroll down the Capabilities list and enable NFC Tag Reading.

  3. Click Save and confirm.

Natively Dashboard Setup

Before proceeding with the iOS app, make sure you have completed the App Capabilities Configuration (iOS only) step above.

  1. Open your Natively app dashboard and navigate to Features > NFC.

  2. Toggle the feature to Enabled.

  3. Enter the Permission Description.

  4. Click Save.

  5. Rebuild your app(s).

The Permission Description is the text shown to users when the OS asks them to grant NFC access. Explain clearly why your app needs this permission - for example: "This app uses NFC to read and write contactless cards."

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code), JavaScript SDK (Code), or AI Agents (for AI-powered editors like Lovable, Base44, and Replit).

Initialization

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

  1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.

  2. Check Installed Plugins: Look through your list of installed plugins for "Natively iOS & Android app builder".

    • If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

  • If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

Setup Logic

[Element] Natively - NFC

Fields:

  • Read Alert Message - message shown to the user when the NFC scanner is waiting for a tag to be placed near the device.

  • Write Alert Message - message shown to the user when the NFC scanner is waiting for a tag to be placed near the device for writing.

  • Read Detected Message - message shown when a tag is successfully detected and read.

  • Write Detected Message - message shown when a tag is successfully detected and data has been written.

  • nfcresponse - a predefined Bubble type Natively - NFCResponse that needs to be selected when working with NFC tag data.

Events:

  • NFC Read Failed - fires when a read attempt fails.

  • NFC Write Failed - fires when a write attempt fails.

  • NFC Write Success - fires when data is successfully written to a tag.

  • NFC Read Success - fires when a tag is successfully read.

  • NFC Ready To Use - fires when the NFC Is Available state is received (useful for Android to confirm NFC is enabled on the device).

States:

  • Error - error message if a read or write attempt failed.

  • Result - the NFC tag result data.

  • NFC Tag ID - the ID of the detected NFC tag.

  • NFC Tag Type - the type of the detected NFC tag.

  • NFC Is Available - Yes/No. Whether NFC is available on the device.

Actions:

  • Read Data - starts an NFC read scanning session.

  • Write Data - starts an NFC write scanning session:

    • Record Data - the data to write to the tag (text or URL). To open your app when the tag is scanned, use your Bundle ID scheme β€” for example: com.bundle.id://open?url={url} .

    • Record ID - a string identifier stored alongside the record on the tag. Only one record can currently be stored per tag, so this doesn't yet enable reading or writing multiple records.

    • Record Data Type - text or uri. When set to uri, scanning the written tag will automatically open the link in the device's default browser.

How to use

Always check availability first

Call nfcService.available() before showing any NFC-related UI to confirm the device supports NFC. On Android, the user may also need to enable NFC in their device settings - handle this gracefully by showing a message directing them to do so if NFC is unavailable.

Use descriptive alert messages

The alert messages shown during scanning sessions are the only feedback the user gets while waiting for a tag. Make them clear and actionable - for example: "Hold your phone near the card to scan" rather than a generic message.

Read vs Write

Use read to retrieve data from an existing NFC tag - for example, to authenticate a product, check in a user, or retrieve a URL. Use write to program a new or blank tag with data your app provides.

Only one record can be stored per tag

recordId is stored alongside the data you write, but tags currently support a single record - you can't write multiple records to the same tag and read them back individually.

When writing a tag with recordDataType: "uri", scanning that tag on any NFC-enabled device will automatically open the URL in the device's default browser - even outside your app. This is useful for product cards, event badges, or any physical object that should direct users to a web page.

Use your Bundle ID scheme to open your app from a tag

To make a scanned tag open your app directly, write your app's Bundle ID scheme as the Record Data - for example com.example.app://open?url=https://yourapp.com. This works in combination with Universal Links and the uri data type.

Supported NFC tags

The app supports NDEF-formatted tags following the NFC Forum Type 2 (NTAG213, NTAG215, NTAG216, MIFARE Ultralight) and Type 5 (ISO15693) standards. Proprietary or non-NDEF cards - payment cards, access cards, MIFARE Classic, DESFire - are not supported.

Troubleshooting

NFC is not working on the device

On Android, the user may need to enable NFC in their device settings before it can be used. The exact location varies by manufacturer - typically found under Settings > Connected devices > NFC. Use nfcService.available() to check if NFC is enabled before attempting to read or write.

NFC is not available on the iOS simulator or Android emulator

NFC requires a physical device with NFC hardware. It will not work on simulators or emulators. Test on a real device only.

Tag not detected during read or write

Make sure you are using a supported tag type - only NTAG213, NTAG215, and NTAG216 (MiFare Ultralight) have been tested and confirmed to work. Hold the device steady and close to the tag during scanning.

Write succeeds, but scanning the tag doesn't open the URL

Make sure recordDataType is set to uri and that the URL is valid and complete (including https://). If recordDataType is set to text, the tag content will be read as plain text and won't trigger a browser open.

App not opening when tag is scanned

Verify that the Bundle ID scheme is correctly formatted in the Record Data - for example com.example.app://open?url=https://yourapp.com. On iOS, Universal Links may need to be configured for the deep link to work correctly.

Last updated