diff --git a/.github/workflows/publish-android.yml b/.github/workflows/publish-android.yml new file mode 100644 index 0000000..c5dd721 --- /dev/null +++ b/.github/workflows/publish-android.yml @@ -0,0 +1,35 @@ +name: Publish Native Android Library + +on: workflow_dispatch + +jobs: + publish-android: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + steps: + - uses: actions/checkout@v4 + - name: set up JDK 17 + uses: actions/setup-java@v4 + with: + java-version: '17' + distribution: 'adopt' + - name: Grant execute permission for gradlew + run: chmod +x ./gradlew + - name: Grant execute permission for publishing script + run: chmod +x ./scripts/publish-android.sh + - name: Make local props + run: | + cat << EOF > "local.properties" + ossrhUsername=${{ secrets.ANDROID_OSSRH_USERNAME }} + ossrhPassword=${{ secrets.ANDROID_OSSRH_PASSWORD }} + sonatypeStagingProfileId=${{ secrets.ANDROID_SONATYPE_STAGING_PROFILE_ID }} + signing.keyId=${{ secrets.ANDROID_SIGNING_KEY_ID }} + signing.password=${{ secrets.ANDROID_SIGNING_PASSWORD }} + signing.key=${{ secrets.ANDROID_SIGNING_KEY }} + EOF + echo "local.properties file has been created successfully." + - name: Run publish script + working-directory: ./scripts + run: ./publish-android.sh \ No newline at end of file diff --git a/.github/workflows/github_actions.yml b/.github/workflows/run-unit-tests.yml similarity index 59% rename from .github/workflows/github_actions.yml rename to .github/workflows/run-unit-tests.yml index b164667..c91eb2b 100644 --- a/.github/workflows/github_actions.yml +++ b/.github/workflows/run-unit-tests.yml @@ -1,4 +1,4 @@ -name: GitHub Actions +name: Run Unit Tests on: workflow_dispatch: @@ -31,11 +31,12 @@ jobs: - name: Code Coverage run: bundle exec fastlane coverage - - name: Setup sonarqube - uses: warchant/setup-sonar-scanner@v8 + # Commenting Sonarqube steps for now, until we are able to configure Sonarqube in Ionic repos + #- name: Setup sonarqube + # uses: warchant/setup-sonar-scanner@v8 - - name: Send to Sonarcloud - run: bundle exec fastlane sonarqube - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} \ No newline at end of file + #- name: Send to Sonarcloud + # run: bundle exec fastlane sonarqube + # env: + # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..556b85d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] + +### 2025-01-08 +- Feat: Add workflows to run unit tests and release the library in Maven repo. + +### 2025-01-07 +- Feat: Add implementation for whole library, including `getCurrentPosition`, `watchPosition`, and `clearWatch`. +- Chore: Create repository. diff --git a/LICENSE b/LICENSE index 83a02f3..774efa0 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2024 OutSystems +Copyright (c) 2025 Ionic Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index f7f4c3f..b0e6684 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,112 @@ -# OSGeolocationLib-Android +# OSGeolocationLib -The `OSGeolocationLib-Android` is a library built using `Kotlin`. +The `OSGeolocationLib-Android` is a library built using `Kotlin` that provides geolocation features for Android applications. + +The `OSGLOCController` class provides the main features of the Library, which are: +- obtaining the location/position of the device a single time; +- adding a watch to obtain periodic location updates; +- clearing/removing a previously added watch, turning off location updates. + + +## Index + +- [Motivation](#motivation) +- [Usage](#usage) +- [Methods](#methods) + - [Obtain the current location of the device](#obtain-the-current-location-of-the-device) + - [Add a watch for periodic location updates](#add-a-watch-for-periodic-location-updates) + - [Clear a watch that was added previously](#clear-a-watch-that-was-added-previously) +- [Troubleshooting](#troubleshooting) +- [Contributing](#contributing) +- [License](#license) +- [Support](#support) + +## Motivation + +This library is used by the Geolocation Plugin for [OutSystems' Cordova Plugin](https://github.com/ionic-team/cordova-outsystems-geolocation) and [Ionic's Capacitor Plugin](https://github.com/ionic-team/outsystems-geolocation). + +## Usage + +In your app-level gradle file, import the `OSGeolocationLib` library like so: + + dependencies { + implementation("com.capacitorjs:osgeolocation-android:1.0.0") + } + + +## Methods + +As mentioned before, the library offers the `OSGLOCController` class that provides the following methods to interact with: + +### Obtain the current location of the device + +```kotlin +suspend fun getCurrentPosition( + activity: Activity, + options: OSGLOCLocationOptions +): Result +``` + +The method is composed of the following input parameters: +- **activity**: the `Activity` from the app using the library to use when obtaining the location. +- **options**: `OSGLOCLocationOptions` with the options with which to make the location request with (e.g. timeout). + +The method returns a `Result` containing either an object of type `OSGLOCLocationResult`, which includes the geolocation data (e.g. latitide, longitude), or an exception that should be handled by the caller app. + +### Add a watch for periodic location updates + +```kotlin +fun addWatch( + activity: Activity, + options: OSGLOCLocationOptions, + watchId: String +): Flow>> +``` + +The method is composed of the following input parameters: +- **activity**: the `Activity` from the app using the library to use when obtaining the location updates. +- **options**: `OSGLOCLocationOptions` with the options with which to make the location updates request with (e.g. timeout). +- **watchId**: a unique id identifying the watch to add, so that it can be removed later. + +The method returns a Flow in which the location updates will be emitted to. + +### Clear a watch that was added previously + +```kotlin +fun clearWatch(id: String): Boolean +``` + +The method is composed of the following input parameters: +- **id**: the `watchId` identigying the watch to remove. + +The method returns a Boolean indicating if the watch was cleared or not (in case the watch isn't found). + +## Troubleshooting + +Common issues and solutions: + +1. Location updates not received + - Check that location permission is allowed on the device + - Verify location services are enabled on the device + - Ensure the necessary permissions are included in `AndroidManifest.xml` + +2. Poor accuracy + - Enable high accuracy mode + - Ensure clear sky view + - Wait for better GPS signal + +## Contributing + +1. Fork the repository +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +## License + +`OSGeolocationLib` is available under the MIT license. See the [LICENSE](LICENSE) file for more info. + +## Support + +- Report issues on our [Issue Tracker](https://github.com/ionic-team/OSGeolocationLib-Android/issues) \ No newline at end of file diff --git a/build.gradle b/build.gradle index 064f71b..b988dc1 100644 --- a/build.gradle +++ b/build.gradle @@ -44,7 +44,7 @@ android { compileSdk 35 defaultConfig { - minSdk 26 + minSdk 23 targetSdk 35 versionCode 1 versionName "1.0" diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md deleted file mode 100644 index ffa5173..0000000 --- a/docs/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -### 2024-02-01 -- Fix: Update `github_actions.yml` file steps versions (https://outsystemsrd.atlassian.net/browse/RMET-2568). - -### 2022-04-12 -Create repository. diff --git a/docs/LICENSE b/docs/LICENSE deleted file mode 100644 index c2979b0..0000000 --- a/docs/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2022 OutSystems - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 1633751..0000000 --- a/docs/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# OSGeolocationLib - -Welcome to **OSGeolocationLib**. This repository serves as a template to create repositories used to build Android libraries. This file will guide you through that process, that is defined by two sequential steps: - -1. Use the current repository as the template for the new one. -2. Clone the new repository on our machine. -3. Run a script that updates the created repository with the correct information. - -These steps are detailed in the next sections. - -:warning: Every step listed here must be successfully completed before you start working on the new repository. - -## Create a Repository Based on the Template - -First, we need to create a new repository. To accomplish this, please press the **Use this template** button available on the repository's GitHub webpage. - -![Use this template button](./assets/useThisTemplateButton.png) - -Next, we have to define the new repository's name. In order to get the maximum performance of the following step, we advise you to use the **[ProjectName]Lib-Android** format for the name. The names used for the **Health and Fitness** and the **Social Logins** are valid examples of the expected format (_OSHealthFitnessLib-Android_ and _OSSocialLoginsLib-Android_ respectively). - -The following image shows an example of the creation of a repository for the Android' Payments Library. - -![Example for payments repository name](./assets/repositoryNameExample.png) - -After filling up the form as needed, the last step to effectively create the repository is the click on the **Create repository from template** button. - -![Create repository from template button](./assets/createRepositoryButton.png) - -## Clone the New Repository - -After completing the previous step, the next one is something common done in every repository a developer needs to do work on: clone the repository on the local machine. - -## Run the **generator_script.sh** - -To finish the process, we just have one last thing to do. Run the **generator_script.sh** script that automates a couple of changes we need to apply. It is included in the _scripts_ folder. - -To run the script, please execute the following commands on **Terminal**: - -``` -cd scripts -sh generator_script.sh -``` - -Here's the complete list of what the script does: - -- The script provides a bit of information, such as mentioning the name that it will use as the Library name (its based on the one you used while creating the repository on GitHub). -- Requests the user for the application's package identifier. The format required is provided and needs to be complied with in order to advance. -- It informs that the script itself will be deleted, as it is a one time execution only. -- It performs the needed changes, replacing all placeholder's organisational identifier and library name for the ones provided by the user. -- To conclude, the script commits and pushes the changes to the remote repository. diff --git a/docs/assets/createRepositoryButton.png b/docs/assets/createRepositoryButton.png deleted file mode 100644 index 423ed4a..0000000 Binary files a/docs/assets/createRepositoryButton.png and /dev/null differ diff --git a/docs/assets/repositoryNameExample.png b/docs/assets/repositoryNameExample.png deleted file mode 100644 index a381131..0000000 Binary files a/docs/assets/repositoryNameExample.png and /dev/null differ diff --git a/docs/assets/useThisTemplateButton.png b/docs/assets/useThisTemplateButton.png deleted file mode 100644 index 22dab19..0000000 Binary files a/docs/assets/useThisTemplateButton.png and /dev/null differ diff --git a/docs/pull_request_template.md b/docs/pull_request_template.md deleted file mode 100644 index 8127c95..0000000 --- a/docs/pull_request_template.md +++ /dev/null @@ -1,32 +0,0 @@ -## Description - - -## Context - - - -## Type of changes - -- [ ] Fix (non-breaking change which fixes an issue) -- [ ] Feature (non-breaking change which adds functionality) -- [ ] Refactor (cosmetic changes) -- [ ] Breaking change (change that would cause existing functionality to not work as expected) - -## Platforms affected -- [ ] Android -- [ ] iOS -- [ ] JavaScript - -## Tests - - - -## Screenshots (if appropriate) - -## Checklist - -- [ ] Pull request title follows the format `RNMT-XXXX ` -- [ ] Code follows code style of this project -- [ ] CHANGELOG.md file is correctly updated -- [ ] Changes require an update to the documentation - - [ ] Documentation has been updated accordingly diff --git a/scripts/publish-android.sh b/scripts/publish-android.sh index 65ea5cc..562060a 100755 --- a/scripts/publish-android.sh +++ b/scripts/publish-android.sh @@ -5,7 +5,7 @@ LOG_OUTPUT=./tmp/publish-android.txt THE_VERSION=`sed -n 's/.*<version>\(.*\)<\/version>.*/\1/p' ../pom.xml` # Get latest io.ionic:portals XML version info -PUBLISHED_URL="https://repo1.maven.org/maven2/com/capacitorjs/geolocationlib-android/maven-metadata.xml" +PUBLISHED_URL="https://repo1.maven.org/maven2/io/ionic/libs/osgeolocation-android/maven-metadata.xml" PUBLISHED_DATA=$(curl -s $PUBLISHED_URL) PUBLISHED_VERSION="$(perl -ne 'print and last if s/.*<latest>(.*)<\/latest>.*/\1/;' <<< $PUBLISHED_DATA)" @@ -20,7 +20,9 @@ else export SHOULD_PUBLISH=true printf %"s\n" "Attempting to build and publish version $THE_VERSION" + # Publish a release to the Maven repo "$ANDROID_PATH"/gradlew clean build publishReleasePublicationToSonatypeRepository closeAndReleaseSonatypeStagingRepository --no-daemon --max-workers 1 -b "$ANDROID_PATH"/build.gradle -Pandroid.useAndroidX=true > $LOG_OUTPUT 2>&1 + # Stage a version # "$ANDROID_PATH"/gradlew clean build publishReleasePublicationToSonatypeRepository --no-daemon --max-workers 1 -b "$ANDROID_PATH"/build.gradle -Pandroid.useAndroidX=true > $LOG_OUTPUT 2>&1 echo $RESULT diff --git a/scripts/publish-module.gradle b/scripts/publish-module.gradle index 92213c5..c306748 100644 --- a/scripts/publish-module.gradle +++ b/scripts/publish-module.gradle @@ -5,20 +5,15 @@ def LIB_VERSION = System.getenv('THE_VERSION') task androidSourcesJar(type: Jar) { archiveClassifier.set('sources') - //if (project.plugins.findPlugin("com.android.library")) { - from android.sourceSets.main.java.srcDirs - from android.sourceSets.main.kotlin.srcDirs - //} else { - // from sourceSets.main.java.srcDirs - // from sourceSets.main.kotlin.srcDirs - //} + from android.sourceSets.main.java.srcDirs + from android.sourceSets.main.kotlin.srcDirs } artifacts { archives androidSourcesJar } -group = 'com.capacitorjs' +group = 'io.ionic.libs' version = LIB_VERSION afterEvaluate { @@ -26,8 +21,8 @@ afterEvaluate { publications { release(MavenPublication) { // Coordinates - groupId 'com.capacitorjs' - artifactId 'osgeolocationlib-android' + groupId 'io.ionic.libs' + artifactId 'osgeolocation-android' version LIB_VERSION // Two artifacts, the `aar` (or `jar`) and the sources @@ -41,13 +36,13 @@ afterEvaluate { // POM Data pom { - name = 'geolocationlib-android' + name = 'osgeolocation-android' description = 'Geolocation Android Lib' - url = 'https://github.com/ionic-team/outsystems-geolocation/packages/android-lib' + url = 'https://github.com/ionic-team/OSGeolocationLib-Android' licenses { license { name = 'License' - url = 'https://github.com/ionic-team/outsystems-geolocation/blob/main/packages/android-lib/LICENSE' + url = 'https://github.com/ionic-team/OSGeolocationLib-Android/blob/main/docs/LICENSE' } } developers { @@ -59,9 +54,9 @@ afterEvaluate { // Version Control Info scm { - connection = 'scm:git:github.com:ionic-team/outsystems-geolocation.git' - developerConnection = 'scm:git:ssh://github.com:ionic-team/outsystems-geolocation.git' - url = 'https://github.com/ionic-team/outsystems-geolocation/tree/main' + connection = 'scm:git:github.com:ionic-team/OSGeolocationLib-Android.git' + developerConnection = 'scm:git:ssh://github.com:ionic-team/OSGeolocationLib-Android.git' + url = 'https://github.com/ionic-team/OSGeolocationLib-Android/tree/main' } } } diff --git a/scripts/publish-root.gradle b/scripts/publish-root.gradle index ea84f30..70e8955 100644 --- a/scripts/publish-root.gradle +++ b/scripts/publish-root.gradle @@ -33,5 +33,5 @@ nexusPublishing { snapshotRepositoryUrl.set(uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")) } } - repositoryDescription = 'OSGeolocation Lib v' + System.getenv('THE_VERSION') + repositoryDescription = 'OSGeolocation Android Lib v' + System.getenv('THE_VERSION') } \ No newline at end of file