This application was developed as school project for Mobile Application Development Project course of Metropolia University of Applied Sciences in Fall 2024 by
Anna Lindén, Dung Pham, Artur Golavskiy and Arman Yerkeshev
 |
 |
 |
 |
|---|
Application contains several quests, consisting of checkpoints, associated with tasks. User can select a quest to follow and perform quest tasks as he progresses. Tasks can be completed in any order. Upon completion of the whole quest user receives an achievement.
Checkpoints are displayed on the map, along with user's current location marker, which updates in real-time.
User needs to be physically present on a location in order to start the task. Currently, only type of quest tasks supported is to take a picture with phone's camera. But in theory, these can be for example, “answer some question about landmark”, "record an audio of the ambiance " etc.
The Hel Quest app incorporates the official Helsinki city colors into its design to ensure the app aligns with local aesthetics. This approach was chosen because the app is intended for local use, and using the city’s official colors helps integrate the product into the local environment in a more meaningful way. The design aligns with Helsinki's identity and provides a more personalized and familiar experience for users in the city.
Programming language of this project is Kotlin v1.9.0
Interactions with the database are handled using Room database. You can find documentation here. All data is saved in phone's local memory. Additionally, Room requires an annotation processor, which, for this project, is KSP.
Interface is created using Jetpack Compose toolkit.
Retrofit, a type-safe HTTP Client for Android and Java, is used to communicate with Overpass API for retrieving Points of Interest data. It parsed the JSON responses into data models using Gson, enabling easy handling of structured data. The parsed data was then processed and inserted into the app's local database for offline access and further usage.
Overpass API is used to retrieve points of interest around a specified location through custom queries. Overpass API is a powerful web-based tool designed to query and retrieve data from the OpenStreetMap (OSM) database. It allows users to access specific map features, such as nodes, ways, and relations, by using a flexible query language called Overpass QL. Common applications include extracting geographic data for custom mapping, analyzing spatial information, or building location-based applications.
For displaying of map and handling user interaction with map and map tile caching, the application uses OpenStreetMap's OSMDroid, version for Composable (credit goes to utsmannn).
Location tracking and possibility of displaying heading directions utilize Fused Location Provider Client and Fused Orientation Provider Client. Both are Google Play services APIs designed for efficient sensor data fusion:
- Fused Location Provider Client simplifies location tracking by combining GPS, Wi-Fi, cell signals, and other data sources. Documentation can be found here.
- Fused Orientation Provider Client (introduced March 2024) provides consistent and reliable device orientation by fusing data from accelerometers, gyroscopes, and magnetometers. Documentation can be found here.
For camera, CameraX is used. Documentation can be found here.
Lastly, JUnit 4 is used for instrumented tests.
Application adheres to MVVM (Model-View-ViewModel) architecture. Data flow from database to UI looks like this:
%%{
init: {
'theme':'base',
'themeVariables': {
'primaryBorderColor': '#000000'
},
'htmlLabels': false
}}%%
flowchart LR;
DataEntity-->DAO-->Repository-->ViewModel-->Composable;
Data is transmitted using Kotlin Flows. This enables UI to automatically recompose every time data changes. When user performs some action, which requires update in the database, data flows in reversed direction:
%%{init: {
'theme':'base',
'themeVariables': {
'primaryBorderColor': '#000000'
},
'htmlLabels': false
}}%%
flowchart LR;
Composable-->ViewModel-->Repository-->DAO-->DataEntity;
This time, data is passed as DataEntities.
Logical structure of data models is expressed in the following picture. Actual implementation is handled by Room dependency, whose documentation can be found here.
Quests are collections of unordered locations (Checkpoints), at which user is expected to perform certain tasks. Quests have names, descriptions and belong to a category (can be anything). System keeps track of whether or not quest was completed and if so, when. Only one quest can be active at a time.
Checkpoints represent locations, to which user needs to arrive in order to progress with the quest. Checkpoints have names, geo-coordinates and an indicator, whether or not checkpoint is completed. Checkpoint can belong to only one quest. Orphan checkpoints are not allowed. Checkpoints can, optionally, have tasks associated with them.
Tasks describe what actions are required from user. They can have a type, denoting which sort of action is expected from user (ex. take a picture, record an audio, answer a question etc.) Additionally, they can hold an answer to the question, when applicable, which can be used to validate user's response. Currently, both type and answer properties are not in use. Tasks can belong to only one checkpoint. Orphan tasks are not allowed.
|--- com.example.androidproject
|--- data
|--- daos
|--- models // i.e. Room Entities
|--- repository
|--- ui
|--- components // UI elements, used in screens
|--- navigation
|--- screens // Logically independent composables, used in navigation
|--- theme // Colours, shapes etc.
|--- viewmodels
|--- utils
In order to start working on this project you will need Android Studio. Download it from here. Set up Android Studio. For Windows, you can follow this guide.
Download this project as .zip and extract or clone it using this command:
git clone git@github.com:A-Yerkeshev/android-project.git
Open project in Android Studio, go to "Gradle Scripts" -> build.gradle.kts. If Android Studio is configured correctly, you will see the top bar with "Sync Now" option. Click it and wait until sync finishes.
You can launch the application on emulator, inside Android Studio (see instructions here) or on real Android phone (instructions here). Note, that application's target Android API is 31, so if you have smaller version, it might not function correctly.
Map is zoomable only with + and - buttons - when zooming with gesture new zooming level is not remembered and zoom level is rolled back upon next map's recomposition.
Related problem - when scrolling the map quickly app doesn't keep up and might not remember the last position and roll back slightly upon next recomposition.