Merge branch 'main' into android-15

Author: pcolby

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog[^1]
 
-## [Unreleased][]
+## [1.4.1][] (2024-06-29)
+
+Added metadata for F-Droid.
+
+## [1.4.0][] (2024-06-22)
 
 Replaced timer with broadcast listener for more responsive tile updates.
 
@@ -34,7 +38,9 @@ Added translations for 86 languages.
 
 Initial release.
 
-[Unreleased]: https://github.com/pcolby/nfc-quick-settings/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/pcolby/nfc-quick-settings/compare/v1.4.1...HEAD
+[1.4.1]: https://github.com/pcolby/nfc-quick-settings/releases/tag/v1.4.1
+[1.4.0]: https://github.com/pcolby/nfc-quick-settings/releases/tag/v1.4.0
 [1.3.1]: https://github.com/pcolby/nfc-quick-settings/releases/tag/v1.3.1
 [1.3.0]: https://github.com/pcolby/nfc-quick-settings/releases/tag/v1.3.0
 [1.2.2]: https://github.com/pcolby/nfc-quick-settings/releases/tag/v1.2.2

README.md

@@ -8,21 +8,63 @@
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=pcolby_nfc-quick-settings&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=pcolby_nfc-quick-settings)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=pcolby_nfc-quick-settings&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=pcolby_nfc-quick-settings)
 
-NFC Quick Settings is a really basic Android app with no GUI of it's own, that simply adds an NFC
-tile to the tiles available to the [Quick Settings panel][].
+NFC Quick Settings is a really basic Android app with no GUI of it's own, that simply adds an NFC tile to the tiles
+available to the [Quick Settings panel][].
 
-*Screenshots go here...*
+The Quick Settings tile indicates the current NFC status (enabled, or disabled), but the action it takes when tapped
+varies a little depending on the permissions available. See [Basic](#basic-mode) and [Advanced](#advanced-mode) modes
+below.
 
-## Internal Details
+[![Get it on Google Play](assets/GetItOnGooglePlay_Badge_Web_color_English.png)](https://play.google.com/store/apps/details?id=au.id.colby.nfcquicksettings)
 
-Just for the curious, the application implements a basic [TileService][], that overrides:
+## Basic Mode
 
-* [onStartListening()][] to check the default NFC adapter's current status, and update the tile state
-  accordingly; and
-* [onClick()][] to show the device's NFC Settings by starting the [NFC Settings][] activity.
+In the _basic_ mode, which requires no special permissions, tapping the tile will simply open the device's NFC Settings
+page (assuming the device has one). This is actually the best that can be done using official Android APIs.
 
-[NFC Settings]: https://developer.android.com/reference/android/provider/Settings#ACTION_NFC_SETTINGS
-[onClick()]: https://developer.android.com/reference/android/service/quicksettings/TileService#onClick()
-[onStartListening()]: https://developer.android.com/reference/android/service/quicksettings/TileService#onStartListening()
-[Quick Settings panel]: https://support.google.com/android/answer/9083864
-[TileService]: https://developer.android.com/reference/android/service/quicksettings/TileService
+## Advanced Mode
+
+The advanced mode requires special permissions (see below), but once enabled, tapping the NFC Quick Settings tile will
+turn the NFC service on or off directly, without having to open the NFC settings page at all. Unfortunately, to acheive
+this _advanced_ mode, NFC Quick Settings needs to use APIs not intended for third-party applications (specifically
+[`NfcAdapter::enable()`][] and [`NfcAdapter::disable()`][]), and to use those methods the tile needs the special
+[`WRITE_SECURE_SETTINGS`][] permission.
+
+### Granting `WRITE_SECURE_SETTINGS` Permission
+
+As the [`WRITE_SECURE_SETTINGS`][] permission is not intended to be used by third-party applications, it needs to be
+granted via the [Android Debug Bridge (adb)][] tool.
+
+1. Install [Android Debug Bridge (adb)][]:
+
+   > `adb` is included in the Android SDK Platform Tools package. Download this package with the [SDK Manager][], which
+   > installs it at `android_sdk/platform-tools/`. If you want the standalone Android SDK Platform Tools package,
+   > [download it here](https://developer.android.com/tools/releases/platform-tools).
+
+2. Install NFC Quick Settings, via [Google Play] or [GitHub Releases].
+
+3. [Enable adb debugging on your device](https://developer.android.com/tools/adb#Enabling).
+
+4. [Connect your device via Wi-Fi](https://developer.android.com/tools/adb#connect-to-a-device-over-wi-fi).
+
+5. Grant the permission to NFC Quick Settings via `adb`:
+
+   ```sh
+   adb shell pm grant au.id.colby.nfcquicksettings android.permission.WRITE_SECURE_SETTINGS
+   ```
+
+If for some reason you want to revoke the [`WRITE_SECURE_SETTINGS`][] permission, and restore the _basic_ mode, then
+simply follow the same steps as above, but replace `grant` with `revoke`. That is, run:
+
+```sh
+adb shell pm revoke au.id.colby.nfcquicksettings android.permission.WRITE_SECURE_SETTINGS
+```
+
+[`NfcAdapter::disable()`]: https://cs.android.com/android/platform/superproject/+/main:frameworks/base/core/java/android/nfc/NfcAdapter.java;l=986?q=NfcAdapter "android.nfc.NfcAdapter::disable()"
+[`NfcAdapter::enable()`]: https://cs.android.com/android/platform/superproject/+/main:frameworks/base/core/java/android/nfc/NfcAdapter.java;l=947?q=NfcAdapter "android.nfc.NfcAdapter::enable()"
+[`WRITE_SECURE_SETTINGS`]: https://developer.android.com/reference/android/Manifest.permission#WRITE_SECURE_SETTINGS "android.permission.WRITE_SECURE_SETTINGS"
+[Android Debug Bridge (adb)]: https://developer.android.com/tools/adb "Android Debug Bridge (adb)"
+[GitHub Releases]: https://github.com/pcolby/nfc-quick-settings/releases "NFC Quick Settings releases"
+[Google Play]: https://play.google.com/store/apps/details?id=au.id.colby.nfcquicksettings "NFC Quick Settings on Google Play"
+[SDK Manager]: https://developer.android.com/studio/intro/update#sdk-manager "Update your tools with the SDK Manager"
+[Quick Settings panel]: https://support.google.com/android/answer/9083864 "Change settings quickly on your Android phone"

app/build.gradle

@@ -30,8 +30,8 @@ android {
         applicationId "au.id.colby.nfcquicksettings"
         minSdk 24
         targetSdkPreview "VanillaIceCream"
-        versionCode 9
-        versionName "1.3.2-pre"
+        versionCode 11
+        versionName "1.4.2-pre"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
     }
 
@@ -64,6 +64,6 @@ dependencies {
     implementation 'androidx.appcompat:appcompat:1.7.0'
     implementation 'com.google.android.material:material:1.12.0'
     testImplementation 'junit:junit:4.13.2'
-    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
-    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
+    androidTestImplementation 'androidx.test.ext:junit:1.2.1'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
 }

app/src/main/play/contact-email.txt

@@ -0,0 +1 @@
+[email protected]

app/src/main/play/contact-website.txt

@@ -0,0 +1 @@
+https://colby.id.au/

app/src/main/play/listings/en-US/full-description.txt

@@ -0,0 +1,11 @@
+NFC Quick Settings is a simple, open source, utility for quickly checking the device's current NFC status, and enabling or disabling NFC with as few taps as possible.
+
+NFC Quick Settings has no user interface of it's own. Instead, once installed, you will see a new "NFC" tile available when customising your Quick Settings menu. See "Add, remove, or move a setting" in Android Help for more information on customising the Quick Settings menu: https://support.google.com/android/answer/9083864?hl=en#customize_settings
+
+Once the NFC Quick Settings tile has been added to your Quick Settings menu, the tile will show the current NFC status.
+
+Android security limitations do not allow any third-party apps, such as this, to turn NFC on or off directly, so when tapped, the NFC Quick Settings tile will simply open the device's NFC Settings page (if the device has one), where you can enable or disable NFC as desired.
+
+NFC Quick Settings also has an advanced mode that allows NFC to be toggled directly from the tile, without having to going the NFC Settings page. But this advanced mode requires special permissions, which can only be granted via the Android Debug Bridge on a desktop computer. You can read more about this mode at https://github.com/pcolby/nfc-quick-settings?tab=readme-ov-file#advanced-mode
+
+NFC Quick Settings is freely available under the GPLv3 open source license. The source code is available at https://github.com/pcolby/nfc-quick-settings

app/src/main/play/listings/en-US/graphics/feature-graphic/HX5V4SmkJtXL_1024_500.png

@@ -0,0 +1 @@
+View NFC status, and quickly access NFC settings, from the Quick Settings menu

app/src/main/play/listings/en-US/graphics/icon/ic_launcher-playstore.png

@@ -0,0 +1 @@
+NFC Quick Settings

app/src/main/play/listings/en-US/graphics/phone-screenshots/01-tile-available-b.png

@@ -0,0 +1 @@
+- Added metadata for F-Droid