Un plugin pour lire et écrire des tags NFC dans Flutter

NFC dans Flutter est un plugin pour lire et écrire des tags NFC dans Flutter. Il fonctionne à la fois sur Android et iOS avec une interface de flux simple.

⚠️ Actuellement, seules les balises au format NDEF sont prises en charge.

Usage

Lire les balises NFC

// NFC.readNDEF returns a stream of NDEFMessage
Stream<NDEFMessage> stream = NFC.readNDEF();

stream.listen((NDEFMessage message) {
    print("records: ${message.records.length}");
});

Lire une étiquette NFC

NDEFMessage message = await NFC.readNDEF(once: true).first;
print("payload: ${message.payload}");
// once: true` only scans one tag!

Ecrire dans les balises

Vous pouvez accéder au tag NFC d’un message à l’aide du NDEFMessagec’est .tag propriété. La balise a un .write méthode, qui vous permet d’écrire un message NDEF dans la balise.

Notez que le flux de lecture doit toujours être ouvert lorsque le .write méthode est appelée. Cela signifie que le once argumentation dans .readNDEF() Ne peut pas être utilisé.

Stream<NDEFMessage> stream = NFC.readNDEF();

stream.listen((NDEFMessage message) {
    NDEFMessage newMessage = NDEFMessage.withRecords(
        NDEFRecord.mime("text/plain", "hello world")
    );
    message.tag.write(newMessage);
});

Vous pouvez également utiliser le NFC.writeNDEF(NDEFMessage) méthode, qui encapsule le code ci-dessus avec la prise en charge de la once dispute.

NDEFMessage newMessage = NDEFMessage.withRecords(
    NDEFRecord.mime("text/plain", "hello world")
);
Stream<NDEFTag> stream = NFC.writeNDEF(newMessage);

stream.listen((NDEFTag tag) {
    print("wrote to tag");
});

Si vous ne souhaitez écrire que dans une balise, vous pouvez définir la once argument à vrai.

NDEFMessage newMessage = NDEFMessage.withRecords(
    NDEFRecord.mime("text/plain", "hello world")
);
Stream<NDEFTag> stream = NFC.writeNDEF(newMessage, once: true);

stream.listen((NDEFTag tag) {
    print("only wrote to one tag!");
});

Et si vous préférez utiliser un Future basée sur l’API, vous pouvez attendre le retour du flux .first méthode.

NDEFMessage newMessage = NDEFMessage.withRecords(
    NDEFRecord.type("text/plain", "hello world")
);

await NFC.writeNDEF(newMessage, once: true).first;

Exemple

import 'package:nfc_in_flutter/nfc_in_flutter.dart';

class NFCReader extends StatefulWidget {
    @override
    _NFCReaderState createState() => _NFCReaderState();
}

class _NFCReaderState extends State {
    bool _supportsNFC = false;
    bool _reading = false;
    StreamSubscription<NDEFMessage> _stream;

    @override
    void initState() {
        super.initState();
        // Check if the device supports NFC reading
        NFC.isNDEFSupported
            .then((bool isSupported) {
                setState(() {
                    _supportsNFC = isSupported;
                });
            });
    }

    @override
    Widget build(BuildContext context) {
        if (!_supportsNFC) {
            return RaisedButton(
                child: const Text("You device does not support NFC"),
                onPressed: null,
            );
        }

        return RaisedButton(
            child: Text(_reading ? "Stop reading" : "Start reading"),
            onPressed: () {
                if (_reading) {
                    _stream?.cancel();
                    setState(() {
                        _reading = false;
                    });
                } else {
                    setState(() {
                        _reading = true;
                        // Start reading using NFC.readNDEF()
                        _stream = NFC.readNDEF(
                            once: true,
                            throwOnUserCancel: false,
                        ).listen((NDEFMessage message) {
                            print("read NDEF message: ${message.payload}"),
                        }, onError: (e) {
                            // Check error handling guide below
                        });
                    });
                }
            }
        );
    }
}

Exemple complet dans exemple de répertoire

Installation

Ajouter nfc_in_flutter à ton pubspec.yaml

dependencies:
    nfc_in_flutter: 2.0.5

iOS

Sur iOS, vous devez activer la capacité de communication en champ proche, ajouter une description d’utilisation NFC et un droit NFC.

Activer la lecture des balises de communication en champ proche

Ouvrez votre projet iOS dans Xcode, recherchez la cible de votre projet et accédez à Capacités. Faites défiler jusqu’à « Near Field Communication Tag Reading » et activez-le.

Activation de la « lecture des balises de communication en champ proche »

Ajoute la fonction de lecture de balises NFC à l’ID d’application.
Ajoute le droit d’accès aux formats de session du lecteur d’étiquettes de communication en champ proche au fichier d’autorisations.

de developer.apple.com : création d’une application de lecture de balises NFC

Description de l’utilisation NFC

Ouvrez votre ios/Runner/Info.plist fichier et ajouter un nouveau NFCReaderUsageDescription clé. Sa valeur doit être une description de ce pour quoi vous prévoyez d’utiliser NFC.

<key>NFCReaderUsageDescription</key>
<string>...</string>

Android

Ajoutez ce qui suit à votre application AndroidManifest.xml dossier:

<uses-permission android:name="android.permission.NFC" />

Si votre application a besoin NFC, vous pouvez ajouter ce qui suit pour autoriser son téléchargement uniquement sur les appareils prenant en charge NFC :

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

« Qu’est-ce que le NDEF ? »

Si vous débutez avec NFC, vous pouvez vous attendre à beaucoup de readNFC() appels, mais à la place vous voyez readNDEF() et NDEFMessage. NDEF est juste une norme de formatage dans laquelle les balises peuvent être encodées. Il existe d’autres encodages que NDEF, mais NDEF est le plus courant. Actuellement, NFC dans Flutter ne prend en charge que les balises au format NDEF.

Émulation de carte hôte

NFC dans Flutter prend en charge la lecture à partir de cartes hôtes émulées*.

Pour lire à partir de cartes hôtes émulées, vous devez faire quelques choses.

Appel readNDEF() avec le readerMode argument défini sur une instance de NFCDispatchReaderMode.
Insérez ce qui suit <intent-filter /> dans ton AndroidManifest.xml activité:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

Pas correctement testé sur iOS

⚠️ Plusieurs modes de lecture

Si vous démarrez un readNDEF() stream avec le mode lecteur défini sur une instance de NFCDispatchReaderModetandis qu’un autre flux est actif avec le NFCNormalReaderModeil lancera un NFCMultipleReaderModesException.

Différences de plate-forme

Quand vous appelez readNDEF() sur iOS, Core NFC (le framework iOS qui permet la lecture NFC) ouvre une petite fenêtre. Sur Android, il commence simplement à écouter les lectures de balises NFC en arrière-plan.

image de developer.apple.com : Communication en champ proche

⚠️ Cela gèlera également Flutter lorsqu’il est ouvert. Veuillez envoyer une demande d’extraction si vous pouvez résoudre ce problème.

La gestion des erreurs

Les erreurs ne font pas exception à NFC dans Flutter (ha, comprends). Le flux renvoyé par NFC.readNDEF() peut envoyer 7 exceptions différentes, et pire encore : elles sont différentes pour chaque plateforme !

Voir l’exemple complet dans le exemple de répertoire pour un exemple sur la façon de vérifier les erreurs.

Exceptions pour les deux plateformes

`NDEFReadingUnsupportedException`

Levée lorsqu’une session de lecture est démarrée, mais pas réellement prise en charge.

iOS

`NFCUserCanceledSessionException`

Lancé lorsque l’utilisateur clique sur la fenêtre contextuelle NFC principale Cancel/Done. Si vous n’avez pas besoin de savoir si l’utilisateur a annulé la session, vous pouvez commencer à lire avec le throwOnUserCancel argument défini sur false ainsi: readNDEF(throwOnUserCancel: false)

`NFCSessionTimeoutException`

Core NFC limite les sessions de lecture NFC à 60 secondes. NFCSessionTimeoutException est lancé lorsque la session a été active pendant 60 secondes.

`NFCSessionTerminatedUnexpectedlyException`

Levé lorsque la session de lecture se termine de manière inattendue.

`NFCSystemIsBusyException`

Lancer lorsque la session de lecture échoue parce que le système est trop occupé.

Android

`NFCIOException`

Levée lorsqu’une exception d’E/S se produit. Cela se produira par exemple si une étiquette est perdue lors de la lecture ou si une étiquette n’a pas pu être connectée.