Scan NFC tags in Creatio Mobile

Level: intermediate

note

This functionality is available for Creatio 8.3.2 and later.

Since version 8.3.2, Creatio Mobile enables developers to use NFC (Near Field Communication) to identify physical objects directly from the mobile app.

NFC is a short-range wireless technology that enables mobile devices to read information from nearby NFC tags. These tags are commonly attached to physical assets such as equipment, devices, or inventory items. Each tag contains a factory-assigned serial number that uniquely identifies the tag.

When a user initiates NFC scanning in Creatio Mobile:

The device activates the NFC reader.
The user brings the mobile device close to the NFC tag.
The device reads the NFC tag serial number.
The scan result is returned to the app.

Creatio Mobile and the mobile operating system handle the scanning session automatically. Developers only need to initiate scanning and process the returned result object in custom business logic that associates the scanned ID with a record in Creatio. For example, a mobile app can store the NFC tag ID in an equipment record and use it later to verify the asset during field visits.

This approach is commonly used in field operations. For example, a field sales representative visiting a retail location can scan the NFC tag attached to a refrigerator or cooler. The app reads the tag ID and retrieves the corresponding equipment record in Creatio. This enables the user to quickly confirm the presence of the equipment and access its service history or update its status.

NFC scanning is typically used for scenarios such as equipment verification during field visits, inventory tracking, asset management, and quick access to equipment service history. NFC scanning is not recommended for data entry, storing large amounts of data on tags, or critical operations that do not have a fallback data entry method.

Creatio Mobile supports NFC scanning on both Android and iOS devices. The scanning interface and behavior depend on the mobile operating system.

On Android devices, Creatio Mobile displays a custom scanning interface. After the user initiates scanning, a scanning screen or bottom sheet appears with instructions such as "Hold your device near the NFC tag." The interface shows a progress indicator while the device attempts to detect the tag. In Freedom UI, the scanning interface is typically displayed as a bottom sheet. In Classic UI, the scanning interface is displayed fullscreen. The scanning session usually times out after approximately 60 seconds if no NFC tag is detected.
On iOS devices, Creatio Mobile displays the native NFC reader dialog. This dialog is controlled by the operating system and cannot be customized. The device automatically detects the NFC tag when it is brought close to it and provides haptic feedback when scanning succeeds. The timeout is managed by the operating system and can vary depending on the iOS version.

Recommendations before implementing NFC scanning

Before implementing NFC scanning in Creatio Mobile, follow the recommendations in the table below.

Recommendation	Description
Provide clear instructions to users	Inform users how to perform the scan, for example, instruct them to hold the mobile device close to the NFC tag and keep it near the tag until scanning is complete. Also explain that NFC must be enabled on the device, provide instructions for enabling NFC in settings, and, if needed, show where the NFC antenna is usually located on the device.
Handle different scan outcomes	The scanning operation might finish with different results, such as a successful scan, timeout, cancellation, or an error. The app must process these outcomes correctly. Learn more about possible result types and the structure of the returned object: NFC scan result object. If scanning succeeds, use the returned NFC tag data to: store the tag ID in an asset or equipment record link the physical asset to the corresponding record in Creatio verify asset identity during subsequent visits
Prepare for unavailable NFC functionality	NFC scanning might be unavailable on some devices or in certain environments. This can occur if: the device does not support NFC NFC is disabled in device settings required permissions are not granted In these cases, inform users that NFC scanning is unavailable and provide an alternative way to complete the task.
Provide alternative input methods	Do not rely on NFC scanning as the only way to enter data. If scanning fails, enable users to retry the operation or use an alternative input method. Consider providing alternative options, for example, manual data entry or QR and bar code scanning. Learn more: Scan QR and bar codes.
Use compatible NFC tags	For asset identification scenarios, NFC Forum Type 2 Tags (T2T) are commonly recommended. If tags are attached to metal surfaces, use tags that contain metal protection film to avoid signal interference. Creatio Mobile supports the most common NFC tag technologies, including ISO/IEC 14443 Type A (NFC-A, e.g., MIFARE tags), ISO/IEC 14443 Type B (NFC-B), ISO/IEC 15693 (NFC-V), and FeliCa (NFC-F).

Implement NFC scanning

You can integrate NFC scanning into both Freedom UI and Classic UI mobile pages.

Implement NFC scanning (Freedom UI)

Implement NFC scanning for Freedom UI mobile pages using a custom request handler in a remote module. The request handler initiates the NFC scanning process and processes the scanning result. Learn more: Custom request handler.

1. Create a TypeScript project

Instructions: Create a TypeScript project.

2. Create a custom request that triggers NFC scanning

Open the "index.ts" file.
Inherit the BaseRequest class from the @creatio/mobile-common library.
Import the required functionality from the libraries into the class.
Save the file.

"index.ts" file
/* Import the required functionality from the libraries. */
import {
    BaseRequest,
    CrtRequest
} from "@creatio/mobile-common";

/* Add the "CrtRequest" decorator to the "MyScanNfcRequest" class. */
@CrtRequest({
    type: 'usr.MyScanNfcRequest'
})

export class MyScanNfcRequest extends BaseRequest {}

3. Create a custom request handler that starts the NFC scanning process

Implement a custom request handler.

Open the "index.ts" file.
Add the configuration object that declares the request handler.
- Set the type property to "usr.ScanNfcRequestHandler". The type property specifies the type of handler.
- Set the requestType property to "usr.MyScanNfcRequest." The requestType property specifies the type of request that triggers the handler defined in the type property.
Flag the ScanNfcRequestHandler class using the CrtRequestHandler decorator.
Inherit the BaseRequestHandler class from the @creatio/mobile-common library.
Implement the logic that starts the NFC scanning process.
Implement the logic that handles the scan result.

After the scanning session finishes, the mobile app returns a result object that contains the scan status and, if the scan is successful, NFC tag data. Learn more about the structure and properties of the returned object: NFC scan result object.

Use the type property of the result object to determine how the app handles the scanning outcome. If an error occurs, display a user-friendly message and enable the user to try scanning again or cancel the operation.
Import the required functionality from the libraries into the class.
Save the file.

"index.ts" file
/* Import the required functionality from the libraries. */
import {
    BaseRequestHandler,
    CrtRequestHandler,
    NfcScanService,
    NfcScanResult,
    NfcScanResultType,
    DialogService,
    BaseDialogConfig
} from "@creatio/mobile-common";

/* Add the "CrtRequestHandler" decorator to the "ScanNfcRequestHandler" class. */
@CrtRequestHandler({
    requestType: "usr.MyScanNfcRequest",
    type: "usr.ScanNfcRequestHandler",
    scopes: []
})

export class ScanNfcRequestHandler extends BaseRequestHandler<MyScanNfcRequest> {

    public async handle(request: BaseRequest): Promise<unknown> {

        /* Create an instance of the "NfcScanService" service from "@creatio/mobile-common." */
        const nfcService = new NfcScanService();

        /* Start scanning. */
        console.log("NFC scan START");
        const scanResult: NfcScanResult = await nfcService.scan();

        /* Log scanning completion. */
        console.log("NFC scan END");

        /* Process the scan result. */
        let message = '';
        if (scanResult.type === NfcScanResultType.Success) {

            /* Tag successfully scanned. */
            message = "NFC tag scanned successfully!\n" +
                "NFC tag ID: " + scanResult.rawData.id + "\n" +
                "NFC tag type: " + scanResult.rawData.type;

            /* Process the scanned data. For example, save "id" to a record field.
            await this.updateRecordField('UsrNfcTagId', scanResult.rawData.id);
            */

        } else if (scanResult.type === NfcScanResultType.Cancelled) {

            /* User cancelled the scan. */
            message = 'Scan cancelled by user';

        } else if (scanResult.type === NfcScanResultType.Timeout) {

            /* Scanning finished due to timeout. */
            message = 'Unable to read NFC tag. Try again and hold the device closer to the tag.';

        } else if (scanResult.type === NfcScanResultType.Error) {

            /* Scan error occurred. */
            message = 'Unable to read NFC tag. Try again and hold the device closer to the tag. ' + scanResult.errorMessage;

        } else if (scanResult.type === NfcScanResultType.Unavailable) {

            /* NFC is not available on the device. */
            message = 'NFC is not available. Enable NFC in device settings. ' + scanResult.errorMessage;

        }

        /* Display the scan result. */
        const dialogService = new DialogService(request.$context);
        const config: BaseDialogConfig = {
            title: 'NFC scan result',
            message: message,
            actions: [{
                key: 'ok',
                config: {
                    caption: 'OK',
                    color: 'primary'
                }
            }]
        };
        await dialogService.open(config);

    return this.next?.handle(request);

    }
}

Register the request handler.

Open the "index.ts" file.
Add the ScanNfcRequestHandler handler to the requestHandlers section in the CrtModule decorator.
Import the required functionality from the libraries into the class.
Save the file.

"index.ts" file
/* Import the required functionality from the libraries. */
import {
    CrtModule,
    bootstrapCrtModule,
    DoBootstrap
} from '@creatio/mobile-common';

@CrtModule({
    /* Specify that "ScanNfcRequestHandler" is request handler. */
    requestHandlers: [
        ScanNfcRequestHandler
    ]
})

export class SomeMainAppClass implements DoBootstrap {
    bootstrap(): void {
        bootstrapCrtModule("SomeMainAppClass", SomeMainAppClass);
    }
}

Build the project.
1. Run the npm run build command at the command line terminal of Microsoft Visual Studio Code.
2. Open the "package.json" file.
3. Click → build command.

As a result, Microsoft Visual Studio Code will add the main.js build file to the TypeScript project's directory that is specified in the webpack.config.js file → baseConfig configuration object → output configuration object → path property. Out of the box, Microsoft Visual Studio Code adds the build files to the ../ts_sdk_template_module/out/mobile/SomeMainAppClass project directory.

4. Add the custom request handler to the Freedom UI page

Repeat steps 1-5 of the procedure to add the custom request handler to the Freedom UI page.
Configure the Button component that calls the request handler implemented using remote module. Instructions: Configure the Freedom UI Mobile component.
viewConfig schema section
```
"viewConfig": {
    "type": "crt.Button",
    "caption": "Scan NFC Tag",
    "clicked": {
        "request": "usr.MyScanNfcRequest"
    }
},
```
Synchronize Creatio Mobile with the main Creatio app.
1. Run Creatio Mobile using the emulator created in Android Studio.
2. Log in to Creatio Mobile using the same user credentials as the main Creatio app.
3. Open the Settings page. To do this, click .
4. Go to the Synchronization block.
5. Click Synchronize.
Synchronize the emulator file system if needed. To do this, go to the Device Explorer tab → right-click an arbitrary directory → Synchronize.
Debug the implemented business logic if needed. Instructions: Debug Creatio Mobile in Freedom UI.

As a result, the request handler implemented using remote module will be added to the Freedom UI page and displayed in Creatio Mobile.

When the user clicks the button, the app sends the request that starts the NFC scanning process.

Implement NFC scanning (Classic UI)

To implement NFC scanning for Classic UI mobile pages, add the scanning logic to the source code of the page that must start NFC scanning, for example, to a button click handler or a page method.

To open the NFC scanning screen, use the Terrasoft.util.openFlutterPage utility and specify the "NfcScanScreen" route name.

The onPop() callback receives the scan result after the scanning session finishes.

The returned object contains the scan status and, if the scan is successful, the NFC tag data. Learn more about the structure and properties of the returned object: NFC scan result object.

Terrasoft.util.openFlutterPage({
    routeName: "NfcScanScreen",
    replace: false,
    onPop: function (data) {

        /* Process the scan result. */
        console.log("NFC scan result: ", JSON.stringify(data, null, 2));

        if (data.type === "success") {

            /* Tag successfully scanned. */
            var tagId = data.rawData.id;
            var tagType = data.rawData.type;

            console.log("NFC tag scanned successfully. ID: ", tagId);
            console.log("NFC tag type: ", tagType);

            /* Process the scanned data. For example, save "tagId" to a record field. */

        } else if (data.type === "cancelled") {

            /* User cancelled the scan. */
            console.log("Scan cancelled by user");

        } else if (data.type === "timeout") {

            /* Scanning finished due to timeout. */
            console.log("Unable to read NFC tag. Try again and hold the device closer to the tag.");

        } else if (data.type === "error") {

            /* Scan error occurred. */
            console.log("Unable to read NFC tag. Try again and hold the device closer to the tag.", data.errorMessage);

        } else if (data.type === "unavailable") {

            /* NFC is not available on the device. */
            console.log("NFC is not available. Enable NFC in device settings.", data.errorMessage);

        }
    }
});

Test the implemented NFC scanning functionality

After you implement NFC scanning, test the functionality on different devices and scenarios to ensure scanning works reliably.

We recommend including the following testing steps:

Test scanning on both Android and iOS devices.
Verify that Creatio Mobile correctly handles successful scans, timeouts, errors, and user cancellations.
Test scanning using different NFC tag types.
Ensure that the app correctly processes the returned scan result and stores the tag ID if required.
Test scanning when the tag is attached to a metal surface or when the tag is damaged.
Verify the behavior when NFC is disabled on the device.

Recommendations before implementing NFC scanning​

Implement NFC scanning​

Implement NFC scanning (Freedom UI)​

1. Create a TypeScript project​

2. Create a custom request that triggers NFC scanning​

3. Create a custom request handler that starts the NFC scanning process​

4. Add the custom request handler to the Freedom UI page​

Implement NFC scanning (Classic UI)​

Test the implemented NFC scanning functionality​

See also​