@ohos.nfc.tag (Standard NFC Tags)

The tag module provides APIs for operating and managing NFC tags. The following tag read modes are available:

• Background mode: The device reads the tag by using NFC without starting any application, and then searches for applications based on the tag type. If only one application is matched, the card reading page of that application will be started. If multiple applications are matched, an application selector will be started, asking the user to select an application.
• Foreground mode: A foreground application has priority to read the NFC tag discovered.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Declaring the NFC Tag Background Mode

To enable NFC tages to be read without starting an application, declare NFC-related attributes in the module.json5 file.

{
    "module": {
        // Attributes to declare.

        "abilities": [
            {
                "skills": [
                    {
                        "actions": [
                            // Actions to declare.

                            // Add the nfc tag action.
                            "ohos.nfc.tag.action.TAG_FOUND"
                        ],
                        "uris": [
                            {
                                "type":"tag-tech/NfcA"
                            },
                            {
                                "type":"tag-tech/IsoDep"
                            }
                            // Add other technology if neccessary,
                            // such as NfcB, NfcF, NfcV, Ndef, MifareClassic, MifareUL, and NdefFormatable.
                        ]
                    }
                ]
            }
        ],
        "requestPermissions": [
            {
                "name": "ohos.permission.NFC_TAG",
                "reason": "tag",
            }
        ]
    }
}

NOTE

• The actions field must contain ohos.nfc.tag.action.TAG_FOUND and cannot be changed.
• The type field under uris must start with tag-tech/, followed by NfcA, NfcB, NfcF, NfcV, IsoDep, Ndef, MifareClassic, MifareUL, or NdefFormatable. If there are multiple types, enter them in different lines. Incorrect settings of this field will cause a parsing failure.
• The name field under requestPermissions is mandatory. It must be ohos.permission.NFC_TAG and cannot be changed.

Modules to Import

import tag from '@ohos.nfc.tag';

tag.TagInfo

Before a card with tags is read or written, TagInfo must be obtained to determine the tag technologies supported by the card. In this way, the application can invoke the correct API to communicate with the card.

import tag from '@ohos.nfc.tag';
import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want'

export default class EntryAbility extends UIAbility {
    onCreate(want : Want, launchParam: AbilityConstant.LaunchParam) {
    // Add other code here.

    // want is initialized by the NFC service and contains tagInfo.
    let tagInfo : tag.TagInfo | null = null;
    try {
      tagInfo = tag.getTagInfo(want);
    } catch (error) {
      console.error("tag.getTagInfo catched error: " + error);
    }
    if (tagInfo == null || tagInfo == undefined) {
      console.log("no TagInfo to be created, ignore it.");
      return;
    }

    // Obtain the supported technologies for this found tag.
    let isNfcATag =  false;
    let isIsoDepTag =  false;
    for (let i = 0; i < tagInfo.technology.length; i++) {
      if (tagInfo.technology[i] == tag.NFC_A) {
        isNfcATag = true;
      }

      if (tagInfo.technology[i] == tag.ISO_DEP) {
        isIsoDepTag = true;
      }
      // Also check for technology tag.NFC_B, NFC_F, NFC_V, ISO_DEP, NDEF, MIFARE_CLASSIC, MIFARE_ULTRALIGHT, and NDEF_FORMATABLE.
    }

    // Use NfcA APIs to access the found tag.
    if (isNfcATag) {
      let nfcA : tag.NfcATag | null = null;
      try {
        nfcA = tag.getNfcATag(tagInfo);
      } catch (error) {
        console.error("tag.getNfcATag catched error: " + error);
      }
      // Other code to read or write this tag.
    }

    // Use getIsoDep APIs to access the found tag.
    if (isIsoDepTag) {
      let isoDep : tag.IsoDepTag | null = null;
      try {
        isoDep = tag.getIsoDep(tagInfo);
      } catch (error) {
        console.error("tag.getIsoDep catched error: " + error);
      }
      // Other code to read or write this tag.
    }
    // Use the same code to handle "NfcA/NfcB/NfcF/NfcV/Ndef/MifareClassic/MifareUL/NdefFormatable".
  }
}

tag.getNfcATag^(deprecated)

getNfcATag(tagInfo: TagInfo): NfcATag

Obtains an NfcATag object, which allows access to the tags that use the NFC-A technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. Use tag.getNfcA instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcA⁹⁺

getNfcA(tagInfo: TagInfo): NfcATag

Obtains an NfcATag object, which allows access to the tags that use the NFC-A technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNfcBTag^(deprecated)

getNfcBTag(tagInfo: TagInfo): NfcBTag

Obtains an NfcBTag object, which allows access to the tags that use the NFC-B technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. Use tag.getNfcB instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcB⁹⁺

getNfcB(tagInfo: TagInfo): NfcBTag

Obtains an NfcBTag object, which allows access to the tags that use the NFC-B technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNfcFTag^(deprecated)

getNfcFTag(tagInfo: TagInfo): NfcFTag

Obtains an NfcFTag object, which allows access to the tags that use the NFC-F technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. Use tag.getNfcF instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcF⁹⁺

getNfcF(tagInfo: TagInfo): NfcFTag

Obtains an NfcFTag object, which allows access to the tags that use the NFC-F technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNfcVTag^(deprecated)

getNfcVTag(tagInfo: TagInfo): NfcVTag

Obtains an NfcVTag object, which allows access to the tags that use the NFC-V technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. Use tag.getNfcV instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcV⁹⁺

getNfcV(tagInfo: TagInfo): NfcVTag

Obtains an NfcVTag object, which allows access to the tags that use the NFC-V technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getIsoDep⁹⁺

getIsoDep(tagInfo: TagInfo): IsoDepTag

Obtains an IsoDepTag object, which allows access to the tags that use the ISO-DEP technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNdef⁹⁺

getNdef(tagInfo: TagInfo): NdefTag

Obtains an NdefTag object, which allows access to the tags in the NFC Data Exchange Format (NDEF).

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getMifareClassic⁹⁺

getMifareClassic(tagInfo: TagInfo): MifareClassicTag

Obtains a MifareClassicTag object, which allows access to the tags that use MIFARE Classic.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getMifareUltralight⁹⁺

getMifareUltralight(tagInfo: TagInfo): MifareUltralightTag

Obtains a MifareUltralightTag object, which allows access to the tags that use MIFARE Ultralight.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNdefFormatable⁹⁺

getNdefFormatable(tagInfo: TagInfo): NdefFormatableTag

Obtains an NdefFormatableTag object, which allows access to the tags that are NDEF formattable.

System capability: SystemCapability.Communication.NFC.Tag

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getTagInfo⁹⁺

getTagInfo(want: Want): TagInfo

Obtains TagInfo from Want, which is initialized by the NFC service and contains the attributes required by TagInfo.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.registerForegroundDispatch¹⁰⁺

registerForegroundDispatch(elementName: ElementName, discTech: number[], callback: AsyncCallback<TagInfo>): void

Registers a listener for the NFC tag read event so that the tag can be preferentially dispatched to a foreground application. You can set the supported NFC tag technologies in discTech. The callback returns TagInfo read. This API must be used with tag.unregisterForegroundDispatch in pairs. The registered callback must be unregistered before the tag reading page exits the foreground or is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Example

See the example of tag.unregisterForegroundDispatch.

tag.unregisterForegroundDispatch¹⁰⁺

unregisterForegroundDispatch(elementName: ElementName): void

Unregisters the listener for the NFC tag read event. If the listener is unregistered, the NFC tage discovered will not be dispatched to foreground applications. The registered callback must be unregistered before the tag reading page exits the foreground or is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Example

import Want from '@ohos.app.ability.Want';
import UIAbility from '@ohos.app.ability.UIAbility';
import tag from '@ohos.nfc.tag';
import { BusinessError } from '@ohos.base';
import bundleManager from '@ohos.bundle.bundleManager';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';

let discTech : number[] = [tag.NFC_A, tag.NFC_B]; // replace with the tech(s) that is needed by foreground ability
let elementName : bundleManager.ElementName;
function foregroundCb(err : BusinessError, tagInfo : tag.TagInfo) {
    if (err as BusinessError) {
        if (!err) {
            console.log("foreground callback: tag found tagInfo = ", JSON.stringify(tagInfo));
        } else {
            console.log("foreground callback err: " + (err as BusinessError).message);
            return;
        }
    }
  // Other operations of taginfo.
}

export default class MainAbility extends UIAbility {
    OnCreate(want : Want, launchParam : AbilityConstant.LaunchParam) {
        console.log("OnCreate");
        elementName = {
            bundleName: want.bundleName as string,
            abilityName: want.abilityName as string,
            moduleName: want.moduleName as string
        }
    }

    onForeground() {
        console.log("onForeground");
        try {
            tag.registerForegroundDispatch(elementName, discTech, foregroundCb);
        } catch (e) {
            console.error("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

    onBackground() {
        console.log("onBackground");
        try {
            tag.unregisterForegroundDispatch(elementName);
        } catch (e) {
            console.error("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

    onWindowStageDestroy() {
        console.log("onWindowStageDestroy");
        try {
            tag.unregisterForegroundDispatch(elementName);
        } catch (e) {
            console.error("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

  // Override other lifecycle functions.
}

tag.ndef.makeUriRecord⁹⁺

makeUriRecord(uri: string): NdefRecord

Creates an NDEF record based on the specified URI.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let uri = "https://gitee.com/openharmony"; // Change it to match your case.
    let ndefRecord = tag.ndef.makeUriRecord(uri);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeUriRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeUriRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeUriRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.error("ndefMessage makeUriRecord catched busiError: " + busiError);
}

tag.ndef.makeTextRecord⁹⁺

makeTextRecord(text: string, locale: string): NdefRecord

Creates an NDEF record based on the specified text data and encoding type.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let text = "Hello World";   // change it to be correct.
    let locale = "en"; // change it to be correct.
    let ndefRecord = tag.ndef.makeTextRecord(text, locale);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeTextRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeTextRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeTextRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.error("ndefMessage makeTextRecord catched busiError: " + busiError);
}

tag.ndef.makeMimeRecord⁹⁺

makeMimeRecord(mimeType: string, mimeData: number[]): NdefRecord

Creates an NDEF record based on the specified MIME data and type.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let mimeType = "text/plain";   // change it to be correct.
    let mimeData = [0x01, 0x02, 0x03, 0x04]; // change it to be correct.
    let ndefRecord = tag.ndef.makeMimeRecord(mimeType, mimeData);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeMimeRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeMimeRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeMimeRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.error("ndefMessage makeMimeRecord catched busiError: " + busiError);
}

tag.ndef.makeExternalRecord⁹⁺

makeExternalRecord(domainName: string, type: string, externalData: number[]): NdefRecord

Creates an NDEF record based on application-specific data.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let domainName = "ohos.nfc.application"; // change it to be correct.
    let type = "test"; // change it to be correct.
    let externalData = [0x01, 0x02, 0x03, 0x04]; // change it to be correct.
    let ndefRecord = tag.ndef.makeExternalRecord(domainName, type, externalData);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeExternalRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeExternalRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeExternalRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.error("ndefMessage makeExternalRecord catched busiError: " + busiError);
}

tag.ndef.messageToBytes⁹⁺

messageToBytes(ndefMessage: NdefMessage): number[]

Converts an NDEF message to bytes.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43]; // MUST can be parsed as NDEF Record.
try {
    let ndefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
    let rawData2 = tag.ndef.messageToBytes(ndefMessage);
    console.log("ndefMessage messageToBytes rawData2: " + rawData2);
} catch (busiError) {
    console.error("ndef createNdefMessage busiError: " + busiError);
}

tag.ndef.createNdefMessage⁹⁺

createNdefMessage(data: number[]): NdefMessage

Creates an NDEF message from raw byte data. The data must comply with the NDEF record format. Otherwise, the NDE record list contained in the NdefMessage object will be empty.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43];  // MUST can be parsed as NDEF Record.
try {
    let ndefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
} catch (busiError) {
    console.error("ndef createNdefMessage busiError: " + busiError);
}

tag.ndef.createNdefMessage⁹⁺

createNdefMessage(ndefRecords: NdefRecord[]): NdefMessage

Creates an NDEF message from the NDEF records list.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

let uriRecord = tag.ndef.makeUriRecord("https://gitee.com/openharmony");
let textRecord = tag.ndef.makeTextRecord("Hello World", "en");
let ndefRecords = [uriRecord, textRecord];
try {
    let ndefMessage = tag.ndef.createNdefMessage(ndefRecords);
    console.log("ndef createNdefMessage ndefMessage: " + ndefMessage);
} catch (busiError) {
    console.error("ndef createNdefMessage busiError: " + busiError);
}

TagInfo

Defines the TagInfo object, which provides information about the tag technologies supported by a card.

System capability: SystemCapability.Communication.NFC.Tag

Required permissions: ohos.permission.NFC_TAG

NdefRecord⁹⁺

Defines an NDEF record. For details, see NFCForum-TS-NDEF_1.0.

System capability: SystemCapability.Communication.NFC.Tag

Technology Type Definition

Enumerates the tag technology types.

System capability: SystemCapability.Communication.NFC.Tag

TnfType⁹⁺

Enumerates the TNF types. For details, see NFCForum-TS-NDEF_1.0.

System capability: SystemCapability.Communication.NFC.Tag

NDEF Record RTD

Enumerates the NDEF record types. For details about the RTD, see NFCForum-TS-NDEF_1.0.

System capability: SystemCapability.Communication.NFC.Tag

NfcForumType⁹⁺

Enumerates the NFC Forum tag types.

System capability: SystemCapability.Communication.NFC.Tag

MifareClassicType⁹⁺

Enumerates the MIFARE Classic tag types.

System capability: SystemCapability.Communication.NFC.Tag

MifareClassicSize⁹⁺

Enumerates the sizes of a MIFARE Classic tag.

System capability: SystemCapability.Communication.NFC.Tag

MifareUltralightType⁹⁺

Enumerates the MIFARE Ultralight tag types.

System capability: SystemCapability.Communication.NFC.Tag