Configure NFC Reading

Scans or stops scanning for NFC (near field communication) tags.

Options 

• Action specifies whether to start (Read) or stop (Cancel) scanning for NFC tags.

The following options are used only for Read:

• Script specifies the script to be run when a tag is read, when an error occurs, if the user cancels the operation, or if the operation is canceled by another Configure NFC script step using the Cancel option.

• Parameter (optional) specifies a script parameter for the script.

• Timeout (optional) automatically cancels the Read operation after the specified number of seconds.

• Continuous Reading (optional), if the value is non-zero, sets the script step to read tags until the user taps the Cancel button, until the timeout parameter is met, or until the time limit imposed by the operating system is reached. If this option is zero or not specified, only one tag is read.

• Format Result as JSON (optional), if the value is non-zero, causes Script to receive the NFC tag's data as a JSON object. If this option is zero or not specified, then it receives the data as a multiline string.

Originated in version 

19.0

Description 

Use this script step to scan or stop scanning for NFC tags, which are programmed with a small amount of data. Data in NFC tags is often a URL that uses protocols such as http, tel, fmp, and mailto.

The Get(ScriptParameter) function must be called in the script specified in the Script option to return the NFC tag's data. Depending on the setting of Format Result as JSON, the NFC tag's data is returned either as a JSON object or as a multiline string.

The following table describes each element in the JSON object and each line of the multiline string. For more information on NFC parameters, see the NFC Data Exchange Format (NDEF) specification.

This is an example of an NFC tag's data as a JSON object:

{
  "action" : "TagRead",
  "error" : "",
  "parameter" : "Optional script parameter",
  "payloadCount" : 2,
  "payloads" : 
  [
    {
      "identifier" : "",
      "primary" : "This is the content from the NFC card.",
      "secondary" : "en",
      "type" : "T",
      "typeNameFormat" : 1
    },
    {
      "identifier" : "",
      "primary" : "https://example.com",
      "secondary" : "",
      "type" : "U",
      "typeNameFormat" : 1
    }
  ]
}

This is the same NFC tag data as a multiline string:

1
2
3
4
5
6
7
8
9
10
11
12
TagRead

Optional script parameter
2

This is the content from the NFC card.
T
1

https://example.com
U
1

Notes 

• Only one read operation may be in progress at the same time. If a read operation is in progress when a cancel operation is performed, the read operation is canceled.

• The Open URL script step can be used to open a URL, such as one received from reading an NFC tag.

Example 1

Initiates reading of a single NFC tag and stops after reaching the timeout value specified in the NFC::Timeout field. After the tag is read, the data in the tag is set in the fields specified in the Parse Result sub-script, which is called from the Scan One Finished sub-script.

Main script: Scan One

Go to Layout [ "NFC Tag" ; Animation: None ]
Configure NFC Reading [ Action: Read ; Script: "Scan One Finished" ; Parameter: "The current date and time is " & Get ( CurrentTimestamp ) ; Timeout: NFC::Timeout ; Format result as JSON: 1 ]

Sub-script 1: Scan One Finished

Set Variable [ $scriptParam ; Value: Get ( ScriptParameter ) ]
Perform Script [ Specified: From list ; "Parse Result" ; Parameter: $scriptParam ]
Show Custom Dialog: [ "NFC Scan Finished" ; $scriptParam ]

Sub-script 2: Parse Result

Because Format Result as JSON is set to a non-zero value in the Configure NFC Reading script step in the Scan One script, the Parse Result script parses the tag data as a JSON object.

New Record/Request
Set Field [ NFC::Text ; Get ( ScriptParameter ) ]
Set Field [ NFC::Tag ; JSONGetElement ( NFC::Text ; "payloads[0].primary" ) ]
Set Field [ NFC::PayloadCount ; JSONGetElement ( NFC::Text ; "payloadCount" ) ]
Set Field [ NFC::Result ; JSONGetElement ( NFC::Text ; "action" ) & JSONGetElement ( NFC::Text ; "error" ) ]
Set Field [ NFC::ReadTimestamp ; Get ( CurrentTimestamp ) ]
Set Field [ NFC::ID ; JSONGetElement ( NFC::Text ; "payloads[0].identifier" ) ]
Set Field [ NFC::Type ; JSONGetElement ( NFC::Text ; "payloads[0].type" ) ]
Commit Records/Requests [ With dialog: Off ]

If you prefer to work with a multiline string, set the Format Result as JSON option to zero. Then change the Parse Result script to the following:

New Record/Request
Set Field [ NFC::Text ; Get ( ScriptParameter ) ]
Set Field [ NFC::Tag ; GetValue ( NFC::Text ; 6 ) ]
Set Field [ NFC::PayloadCount ; GetValue ( NFC::Text ; 4 ) ]
Set Field [ NFC::Result ; GetValue ( NFC::Text ; 1) & GetValue ( NFC::Text ; 2 ) ]
Set Field [ NFC::ReadTimestamp ; Get ( CurrentTimestamp ) ]
Set Field [ NFC::ID ; GetValue ( NFC::Text ; 5) ]
Set Field [ NFC::Type ; GetValue ( NFC::Text ; 7) ]
Commit Records/Requests [ With dialog: Off ]

Example 2 

Initiates reading of multiple tags and stops after reaching the timeout value specified in the NFC::Timeout field or if scanning is canceled. As the tags are read, the data in the tag is set in the fields specified in the Parse Result sub-script (see Example 1).

Main script: Scan Multiple

Configure NFC Reading [ Action: Read ; Script: "Parse Result" ; Parameter: "Scanning started at " & Get ( CurrentTimestamp ) ; Timeout: NFC::Timeout ; Continuous Reading: 1 ; Format result as JSON: 1] 
Go to Layout [ "NFC Scan List"; Animation: None ]

Example 3 

Initiates tag reading and attempts to open a URL if the type of the NFC record is "U," indicating the payload is a URL. Scanning stops after reaching the timeout value specified in the NFC::Timeout field or if scanning is canceled. After the tag is read, the data in the tag is set in the fields specified in the Parse Result sub-script (see Example 1), which is called from the Open from Scan sub-script.

Main script: Scan and Open

Configure NFC Reading [ Action: Read ; Script: "Open from Scan" ; Parameter: "Scanning started at " & Get ( CurrentTimestamp ) ; Timeout: NFC::Timeout ; Format result as JSON: 1 ] 
Go to Layout [ "NFC Scan List"; Animation: None ]

Sub-script: Open from Scan

Set Variable [ $scriptParam ; Value: Get ( ScriptParameter ) ]
Perform Script [ Specified: From list ; "Parse Result" ; Parameter: $scriptParam ]
Commit Records/Requests [ With dialog: Off ]
If [ NFC::Type = "U" ]
    Open URL [ With dialog: On ; NFC::Tag ] 
End If

Related topics 

• Script steps reference