@exxili/capacitor-nfc 0.0.2 → 0.0.9

package/ExxiliCapacitorNfc.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'ExxiliCapacitorNfc'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target  = '13.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/README.md

@@ -1,31 +1,33 @@
 # Capacitor NFC Plugin (@exxili/capacitor-nfc)
 
-A Capacitor plugin for reading and writing NFC tags on iOS devices. This plugin allows you to:
+A Capacitor plugin for reading and writing NFC tags on iOS and Android devices. This plugin allows you to:
 
 - Read NDEF messages from NFC tags.
 - Write NDEF messages to NFC tags.
 
-**Note**: NFC functionality is only available on compatible iOS devices running iOS 13.0 or later. Android NFC functionality is still
-in development
+**Note**: NFC functionality is only available on compatible iOS devices running iOS 13.0 or later.
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [iOS Setup](#ios-setup)
-- Android Setup (in Development)
+- [Android Setup](#android-setup)
 - [Usage](#usage)
   - [Reading NFC Tags](#reading-nfc-tags)
   - [Writing NFC Tags](#writing-nfc-tags)
 - [API](#api)
   - [Methods](#methods)
+    - [`isSupported()`](#issupported)
     - [`startScan()`](#startscan)
-    - [`writeNDEF(options)`](#writendefoptions)
+    - [`writeNDEF(options)`](#writendefoptions-ndefwriteoptionst-extends-string--number--uint8array--string)
+    - [`cancelWriteAndroid`](#cancelwriteandroid)
   - [Listeners](#listeners)
-    - [`addListener('nfcTag', listener)`](#addlistenernfctag-listener)
-    - [`addListener('nfcError', listener)`](#addlistenernfcerror-listener)
-    - [`addListener('nfcWriteSuccess', listener)`](#addlistenernfcwritesuccess-listener)
+    - [`onRead(listener)`](#onreadlistener-data-ndefmessagestransformable--void)
+    - [`onError('listener)`](#onerrorlistener-error-nfcerror--void)
+    - [`onWrite(listener)`](#onwritelistener---void)
   - [Interfaces](#interfaces)
     - [`NDEFWriteOptions`](#ndefwriteoptions)
+    - [`NDEFWriteOptions`](#ndefmessagestransformable)
     - [`NDEFMessages`](#ndefmessages)
     - [`NDEFMessage`](#ndefmessage)
     - [`NDEFRecord`](#ndefrecord)
@@ -71,6 +73,15 @@ In your `Info.plist` file (usually located at `ios/App/App/Info.plist`), add:
 
 Replace the description with a message that explains why your app needs NFC access.
 
+## Android Setup
+
+Add the following to your `AndroidManifest.xml` file:
+
+```xml
+<uses-permission android:name="android.permission.NFC" />
+<uses-feature android:name="android.hardware.nfc" android:required="true" />
+```
+
 ## Usage
 
 Import the plugin into your code:
@@ -81,10 +92,10 @@ import { NFC } from '@exxili/capacitor-nfc';
 
 ### Reading NFC Tags
 
-To read NFC tags, you need to start a scanning session and listen for `nfcTag` events.
+To read NFC tags, you need to listen for `nfcTag` events. On iOS, you must also start the NFC scanning session using `startScan()`.
 
 ```typescript
-import { NFC, NDEFMessages, NFCError } from '@exxili/capacitor-nfc';
+import {NFC, NDEFMessagesTransformable, NFCError} from '@exxili/capacitor-nfc';
 
 // Start NFC scanning
 NFC.startScan().catch((error) => {
@@ -92,19 +103,19 @@ NFC.startScan().catch((error) => {
 });
 
 // Listen for NFC tag detection
-const nfcTagListener = NFC.addListener('nfcTag', (data: NDEFMessages) => {
-  console.log('Received NFC tag:', data);
+NFC.onRead((data: NDEFMessagesTransformable) => {
+  console.log('Received NFC tag:', data.string());
 });
 
 // Handle NFC errors
-const nfcErrorListener = NFC.addListener('nfcError', (error: NFCError) => {
+NFC.onError('nfcError', (error: NFCError) => {
   console.error('NFC Error:', error);
 });
 ```
 
 ### Writing NFC Tags
 
-To write NDEF messages to NFC tags, use the `writeNDEF` method and listen for `nfcWriteSuccess` events.
+To write NDEF messages to NFC tags, use the `writeNDEF` method and listen for `onWrite` events.
 
 ```typescript
 import { NFC, NDEFWriteOptions, NFCError } from '@exxili/capacitor-nfc';
@@ -128,12 +139,12 @@ NFC.writeNDEF(message)
   });
 
 // Listen for write success
-const nfcWriteSuccessListener = NFC.addListener('nfcWriteSuccess', () => {
+NFC.onWrite(() => {
   console.log('NDEF message written successfully.');
 });
 
 // Handle NFC errors
-const nfcErrorListener = NFC.addListener('nfcError', (error: NFCError) => {
+NFC.onError((error: NFCError) => {
   console.error('NFC Error:', error);
 });
 ```
@@ -142,9 +153,15 @@ const nfcErrorListener = NFC.addListener('nfcError', (error: NFCError) => {
 
 ### Methods
 
+#### `isSupported()`
+
+Returns if NFC is supported on the scanning device.
+
+**Returns**: `Promise<{ supported: boolean }>`
+
 #### `startScan()`
 
-Starts the NFC scanning session.
+Starts the NFC scanning session on ***iOS only***. Android devices are always in reading mode, so setting up the `nfcTag` listener is sufficient to handle tag reads on Android.
 
 **Returns**: `Promise<void>`
 
@@ -158,13 +175,17 @@ NFC.startScan()
   });
 ```
 
-#### `writeNDEF(options: NDEFWriteOptions)`
+#### `writeNDEF(options: NDEFWriteOptions<T extends string | number[] | Uint8Array = string)`
 
 Writes an NDEF message to an NFC tag.
 
+Payload may be provided as a string, `Uint8Array`, or an array of numbers. The plugin will automatically convert the payload to a byte array for storage on the NFC tag.
+
+Android use: since Android has no default UI for reading and writing NFC tags, it is recommended that you add a UI indicator to your application when calling `writeNDEF` and remove it in the `nfcWriteSuccess` listener callback and the `nfcError` listener callback. This will prevent accidental writes to tags that your users intended to read from.
+
 **Parameters**:
 
-- `options: NDEFWriteOptions` - The NDEF message to write.
+- `options: NDEFWriteOptions<T extends string | number[] | Uint8Array = string>` - The NDEF message to write.
 
 **Returns**: `Promise<void>`
 
@@ -178,55 +199,61 @@ NFC.writeNDEF(options)
   });
 ```
 
+#### `cancelWriteAndroid()`
+
+Cancels an Android NFC write operation. Android does not have a native UI for NFC tag writing, so this method allows developers to hook up a custom UI to cancel an in-progress scan.
+
 ### Listeners
 
-#### `addListener('nfcTag', listener: (data: NDEFMessages) => void)`
+#### `onRead(listener: (data: NDEFMessagesTransformable) => void)`
+
+Adds a listener for NFC tag detection events. Returns type `NDEFMessagesTransformable`, which returns the following methods to provide the payload:
 
-Adds a listener for NFC tag detection events.
+* `string()`: Returns `NDEFMessages<string>`, where all payloads are strings.
+* `base64()`: Returns `NDEFMessages<string>`, where all payloads are the base64-encoded payloads read from the NFC tag.
+* `uint8Array()`: Returns `NDEFMessages<Uint8Array>`, where all payloads are the `Uint8Array` bytes from the NFC tag.
+* `numberArray()`: Returns `NDEFMessages<number[]>`, where all payloads bytes from the NFC tag represented as a `number[]`.
 
 **Parameters**:
 
-- `eventName: 'nfcTag'`
-- `listener: (data: NDEFMessages) => void` - The function to call when an NFC tag is detected.
+- `listener: (data: NDEFMessagesTransformable) => void` - The function to call when an NFC tag is detected.
 
-**Returns**: `PluginListenerHandle`
+**Returns**: `void`
 
 ```typescript
-const nfcTagListener = NFC.addListener('nfcTag', (data: NDEFMessages) => {
+NFC.onRead((data: NDEFMessages) => {
   console.log('Received NFC tag:', data);
 });
 ```
 
-#### `addListener('nfcError', listener: (error: NFCError) => void)`
+#### `onError(listener: (error: NFCError) => void)`
 
 Adds a listener for NFC error events.
 
 **Parameters**:
 
-- `eventName: 'nfcError'`
 - `listener: (error: NFCError) => void` - The function to call when an NFC error occurs.
 
 **Returns**: `PluginListenerHandle`
 
 ```typescript
-const nfcErrorListener = NFC.addListener('nfcError', (error: NFCError) => {
+NFC.onError((error: NFCError) => {
   console.error('NFC Error:', error);
 });
 ```
 
-#### `addListener('nfcWriteSuccess', listener: () => void)`
+#### `onWrite(listener: () => void)`
 
 Adds a listener for NFC write success events.
 
 **Parameters**:
 
-- `eventName: 'nfcWriteSuccess'`
 - `listener: () => void` - The function to call when an NDEF message has been written successfully.
 
 **Returns**: `PluginListenerHandle`
 
 ```typescript
-const nfcWriteSuccessListener = NFC.addListener('nfcWriteSuccess', () => {
+NFC.onWrite('nfcWriteSuccess', () => {
   console.log('NDEF message written successfully.');
 });
 ```
@@ -238,8 +265,26 @@ const nfcWriteSuccessListener = NFC.addListener('nfcWriteSuccess', () => {
 Options for writing an NDEF message.
 
 ```typescript
-interface NDEFWriteOptions {
-  records: NDEFRecord[];
+interface NDEFWriteOptions<T extends string | number[] | Uint8Array = string> {
+  records: NDEFRecord<T>[];
+}
+```
+
+#### `NDEFMessagesTransformable`
+
+Returned by `onRead` and includes the following methods to provide the payload:
+
+* `string()`: Returns `NDEFMessages<string>`, where all payloads are strings.
+* `base64()`: Returns `NDEFMessages<string>`, where all payloads are the base64-encoded payloads read from the NFC tag.
+* `uint8Array()`: Returns `NDEFMessages<Uint8Array>`, where all payloads are the `Uint8Array` bytes from the NFC tag.
+* `numberArray()`: Returns `NDEFMessages<number[]>`, where all payloads bytes from the NFC tag represented as a `number[]`.
+
+```typescript
+interface NDEFMessagesTransformable {
+  base64: ()=> NDEFMessages;
+  uint8Array: ()=> NDEFMessages<Uint8Array>;
+  string: ()=> NDEFMessages;
+  numberArray: ()=> NDEFMessages<number[]>;
 }
 ```
 
@@ -265,10 +310,10 @@ interface NDEFMessage {
 
 #### `NDEFRecord`
 
-An NDEF record.
+An NDEF record. `payload` is, by default, an array of bytes representing the data; this is how an `NDEFRecord` is read from an NFC tag. You can choose to provide an `NDEFRecord` as a string a `Uint8Array` also.
 
 ```typescript
-interface NDEFRecord {
+interface NDEFRecord<T = number[]> {
   /**
    * The type of the record.
    */
@@ -277,9 +322,9 @@ interface NDEFRecord {
   /**
    * The payload of the record.
    */
-  payload: string;
+  payload: T;
 }
-```
+````
 
 #### `NFCError`
 
@@ -320,18 +365,26 @@ Here's a complete example of how to read and write NFC tags in your app:
 ```typescript
 import { NFC, NDEFMessages, NDEFWriteOptions, NFCError } from '@exxili/capacitor-nfc';
 
-// Start NFC scanning
+// Check if NFC is supported
+const { supported } = await NFC.isSupported();
+
+// Start NFC scanning -- iOS only
 NFC.startScan().catch((error) => {
   console.error('Error starting NFC scan:', error);
 });
 
 // Listen for NFC tag detection
-const nfcTagListener = NFC.addListener('nfcTag', (data: NDEFMessages) => {
-  console.log('Received NFC tag:', data);
+NFC.onRead((data: NDEFMessages) => {
+  const stringMessages: NDEFMessage<string> = data.string();
+  const uint8ArrayMessages: NDEFMessage<Uint8Array> = data.uint8Array();
+  
+  // Print all Uint8Array payloads
+  console.log('Received NFC tag:', stringMessages.messages?.at(0)?.records?.at(0).payload);    // prints string[]
+  console.log('Received NFC tag:', uint8ArrayPayloads.messages?.at(0)?.records?.at(0).payload);    // prints Uint8Array[]
 });
 
 // Handle NFC errors
-const nfcErrorListener = NFC.addListener('nfcError', (error: NFCError) => {
+NFC.onError((error: NFCError) => {
   console.error('NFC Error:', error);
 });
 
@@ -355,14 +408,14 @@ NFC.writeNDEF(message)
   });
 
 // Listen for write success
-const nfcWriteSuccessListener = NFC.addListener('nfcWriteSuccess', () => {
+NFC.onWrite('nfcWriteSuccess', () => {
   console.log('NDEF message written successfully.');
 });
 ```
 
 ## License
 
-[MIT License](LICENSE)
+[MIT License](https://opensource.org/license/mit)
 
 ---
 

package/android/build.gradle

@@ -6,22 +6,27 @@ ext {
 }
 
 buildscript {
+    ext {
+        kotlin_version = '2.1.21'
+    }
     repositories {
         google()
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.2.1'
+        classpath 'com.android.tools.build:gradle:8.2.2'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
 
 apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
 
 android {
     namespace "com.exxili.capacitornfc"
     compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
     defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 22
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 33
         targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
         versionCode 1
         versionName "1.0"
@@ -40,6 +45,9 @@ android {
         sourceCompatibility JavaVersion.VERSION_17
         targetCompatibility JavaVersion.VERSION_17
     }
+    kotlinOptions {
+        jvmTarget = '17'
+    }
 }
 
 repositories {
@@ -52,6 +60,7 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation 'androidx.core:core-ktx:1.16.0'
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

package/android/src/main/kotlin/com/exxili/capacitornfc/MainActivity.kt

@@ -0,0 +1,11 @@
+package com.exxili.capacitornfc
+
+import android.os.Bundle
+import com.getcapacitor.BridgeActivity
+
+class MainActivity : BridgeActivity() {
+    public override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        registerPlugin(NFCPlugin::class.java)
+    }
+}